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
InfoQ.com has a lot of great REST resources including this overview of RESTful systems by Subbu Allamaraju.
This week in REST: http://thisweekinrest.wordpress.com/
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 http://oredev.org/2010/
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.
Check out this example of going through an OAuth client registration using the Google+ API as a demo.
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 (vnd.foxycart.com.user.v1+json) 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.