Sunday, February 26, 2012

RESTful Resources Required Reading

A couple months ago, I began a journey to learn and build my first RESTful API. I've built APIs before and have worked with REST systems in the past, but I didn't know what I didn't know, ya know? I still have plenty to learn, but I'm starting to wrap my head around the ideas that make up the REST principles.

This blog hasn't been very technical lately, so here's one for my hacker homies: the REST resources I've been consuming lately. I hope they help you as they have helped me and I will probably keep them updated so please send me any additional links I should include.

If you're serious about REST, just start here: Roy Field's dissertation, chapter 5 on REST
Then read all of Apigee's REST blogs posts for the latest best practices. Then read them again.
After that, watch this webinar that brings them all together: RESTful API Design

Martin Fowler discussing Leonard Richardson's various levels of REST:
  • Level 0: The Swamp of POX (Plain Old XML)
  • Level 1: Resources
  • Level 2: HTTP Verbs
  • Level 3: Hypermedia Controls has a lot of great REST resources including this overview of RESTful systems by Subbu Allamaraju.

This week in REST:

rest-discuss on Yahoo
API Craft on Google <-- this one seriously rocks

Great article by Steve Klabnik discussing how no one is really using Hypertext As The Engine Of Application State (yet): Haters gonna HATEOAS

Learning what not to do is often helpful:
REST worst practices
Some Do's and Don'ts of URI design

Great post comparing GitHub and Twilio's RESTAPIs

I'm still not sure about this one, but you should at least know about the standards being worked on related to REST APIs: Web Resource Modeling Language

I'm not sure agree with the conclusions on this next one related to duplicating data in the body that can be represented in the headers, but if you're dealing with some proxies that strip custom headers, definitely give this a read: REST is a set of principles and not animplementation

Some great slideshares and presentations you should watch:
Jim Webber's Hypermedia: The Confusing bit from REST
Thomas Steiner and Jan Algermissen's Fulfilling the Hypermedia Constraintvia OPTIONS, Link Headers and the HTTP Vocabulary in RDF
Jon Moore discussing Hypermedia APIs at
A great "why" presentation from Sam Ramji on the need to build out a powerful API and make it the core of your business process: API Driven Internet

Some more interesting tools and standards:
A very simple PHP REST wrapper: Resty
I haven't (yet) dove into building out a truly RESTful client, but RESTAgent sounds pretty cool.
HAL: Hypertext Application Language

Oh yeah, don't forget about the power of caching when it comes to REST. Read up on using Etags and Preconditions to ensure you don't stomp an existing update.

You should memorize the HTTP Status Codes but do it using this page which describes them as LOL cats. Much more entertaining.

API Examples:

OAuth 2.0
Sales Force
Check out this example of going through an OAuth client registration using the Google+ API as a demo.
Facebook Authentication
37 Signals

This is an ongoing journey for me. As I said, I have plenty more to learn, but things are slowly starting to come together. I'm getting excited about what the future of API development could be if we all agree upon REST standards and start building clients that understand how to work with consistent media types and hyperlinks. If your business is worth building, the services you provide should stand the test of time. REST (as HTTP and the World Wide Web have already proven) can help us get there.

I plan to post more about this and/or update this entry as I learn more. Here are some questions I've been thinking through in the past week or so:
  • Should we use the Link header exclusively and not include links in the body? What about when we're responding with nested resources? Is it strange to use both?
    • My current leaning is to include a _links (similar to what HAL uses) node in the body response for all resources just to reinforce the importance of using Hypermedia when building out the client.
  • Does it makes sense to version individual resources ( AND use a custom version header (X-API-VERSION)?
    • I'm currently thinking yes... since this would give us a lot of flexibility. Say, for example, a really important client needs a new feature right away on a specific resource. Instead of upgrading the entire API, we could create a new versioned media type for that resource. Since they would be the only ones requesting that resource via the Accept header, the risk to other clients is 0. When we do roll out a completely new version, the X-API-VERSION header (which we require from the start) can be updated.
  • What are your thoughts on the HTTP Vocabulary in RDF (Resource Description Framework)?
    • I still don't know much about this. Should I?
  • What are your thoughts on HAL or Collection+JSON?
    • I like them a lot, but decided against them (for now) in that I want the resource to be as "clean" as possible in that it only contains data that pertains to that resource. The Link header seems to work for most cases. The downside is the "explosion of custom media types", but as long as a client just replays the media type of the link it's going to follow next via the Accept header, it shouldn't be that big of a deal. If a client has been coded for a specific media type, it can know for sure things will work. That being said, the beauty of REST is that I could implement this later if a client preferred it and all they'd have to do is send the correct Accept header to get the format they want.

What are some REST API related questions you have? Let's start a dialog.


Jon Wolski said...

That's quite a selection of resources you've compiled! This post just became my favorite resource for learning to be RESTful

Luke Stokes said...

Thanks Wolski! It's basically just my bookmarks folder put to a post. I've been trying to learn as much as possible so when we release our new API, hopefully it will make sense. My BHAG is that others will use our API sandbox as a resource to learn REST API best practices. At least with this post, I can point to why we're making the decisions we are.

BTW, you going to start blogging? In spite of what Creed Bratton thinks, a Word doc is not a blog. You have to share your awesomeness with people. :)

davedevelopment said...

Nice post Luke, strangely enough I've been through the same process and blogged about it last week, though my post isn't as well written as yours!

Luke Stokes said...

Thanks for sharing, Dave! Great article, I really enjoyed it.

Luke Stokes said...

I've read this one more than a few times, but I'm surprised I didn't include it here: REST APIs must be hypertext-driven:

Just listening to a talk and was reminded on how this link needs to be included.