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

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/

Newsgroups:
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
Collection+JSON

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:
http://www.peej.co.uk/articles/restfully-delicious.html
http://ajaxpatterns.org/RESTful_Service
Netflix
Bitly
Twilio
Suncloud
Atlassian
Huddle
Stripe

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 (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.

Stereotypes Make You Stupid

Is it really not OK to talk about religion or politics? What if we could have deep, constructive and meaningful conversations about our worldviews and the very essence of our "why" in life without getting into arguments, or worse, being dismissed before the discussion begins? Sure, we could talk about sports, the weather or our jobs, but what has more long-term value? If we could get together and dialogue about how our systems of government work (or don't work, as the case may be), could we actually change things?

What about religion? Let's assume, for a moment, that we really are eternal, spiritual beings and the decisions we make now have significant impact even after our bodies are gone. If that's really true, wouldn't it be worth dialoguing about (even if you have a contrary opinion)?

We could extend the list to include sex, parenting, education and even the foods we eat. All of these are emotionally charged topics stuffed full of strong (often judgmental) opinions. These topics invoke our passions because they involve our beliefs, expectations and desires. In essence, they are important to us.

So why don't we talk about the ideas that are important to us more often and more publicly?

I think part of the answer is summarized in the word stereotype: "A widely held but fixed and oversimplified image or idea of a particular type of person or thing." As long as we only see things through the lens of a stereotype, we'll never be able to really understand where an individual is coming from and what drives their opinions, beliefs and expectations. If we can begin to understand that those we talk with are at least as passionate as we are about a contradicting view, then, just maybe, we can start to engage them in a respectful manner that strengthens our relationship and hopefully deepens our understanding of ourselves and others.

The trick is, both parties involved in the conversation have to be willing to go to that level. If I tell you I'm a "Christian" and you're not willing to get to know me to better understand what that word means to me and how it impacts my life, then you'll most likely be left with an empty shell of who I really am. In many cases, the baggage that word implies can hinder relationship before it even begins. Same thing goes for other words such as Muslim, vegan, home-schooled, homosexual, Atheist, Republican, or Democrat. I could list many more. Which words trigger stereotypes for you?

So is the wise answer to just avoid discussing these topics? I hope not. I really, really hope not. We have freedoms in this country that many men and women have fought and died for. Freedoms that are arguably being eroded on a regular basis. If we don't exercise the freedoms we have, will they matter enough to defend? Great leaders (and great companies for that matter), often encourage and cultivate passionate dialog as part of the decision-making process. They need counter-opinions to better understand their own ideas or to change them as needed. If we think we have it all figured out, we're probably delusional. If we stop learning and growing, we stop improving ourselves and the world around us.

Maybe this is obvious to you, but do you still let it impact how you interact with people? Pick a stereotype that you have some strong opinions about... can you easily look past them in every conversation? I not only struggle at this, but I have failed at it miserably in the past.

I'm actively working to change because I certainly don't have it all figured out and the value of my relationships far outweighs my opinions or the need to be "right" all the time.