This post was originally published on the SmartLogic Blog.
This past weekend, I headed down to REST Fest in Greenville, South Carolina. My weekend lived up to my expectations: though I didn’t get much of a chance to work on Frenetic, I spread the word about Raddocs and RAD, and learned a lot from the API developers at the event.
For those of you who couldn’t make it, here’s a quick wrap-up of three things I learned, and, at the end of the post, the video of my 5in5 talk:
What a bad API looks like
During Mike Amundsen’s presentation he said, “Exposing your database is like showing me your underwear. I don’t wanna see that.” This was both enlightening and disheartening. My previous APIs have been mostly database table to resource. While they do their job, they definitely could be better. In the future I will definitely put more thought into the design of my APIs.
Registering Link Relations and Media Types
Before attending REST Fest, I didn’t know that if you create a short link relation you have to register it with a registry such as IANA or MicroFormats. The way around this is to create link relations as URIs.
An example from the Helpdesk Hackday at REST Fest:
<atom:link rel="http://helpdesk.hackday.2012.restfest.org/rels/ticket" href="http://.../tickets/9172361" type="application/vnd.org.restfest.2012.hackday+xml" />
In the same vein as registering link relations, I didn’t know you were supposed to register media types. The HTTP spec calls for them to be registered in RFC 2616. Here’s the gist: “Media-type values are registered with the Internet Assigned Number Authority (IANA [19]). The media type registration process is outlined in RFC 1590 [17]. Use of non-registered media types is discouraged.”
Linking in JSON
I learned of a new hypermedia format for JSON called Siren. I had previously seen HAL before, but I like that Siren gives you the ability to include actions in the resource. Siren is located here on GitHub.
In addition to learning about Siren, I also learned more about Collection+JSON. I had seen it before but I had only glanced at it. Collection+JSON is located here. I will definitely be giving both of these a more thorough look through for my next API project.
Overall, the weekend was jam packed with new information. Were you there? What was the most useful thing you learned? Comment here or tweet me, @ericoestrich.
And, as promised, here’s my 5in5 talk:
REST Fest 2012 \ Eric Oestrich \ FiveInFive from REST Fest on Vimeo.
