2013-11-30
Collection of REST Resources

While developing RESTful web applications, I have had my share of doubts about designing the API the right way. Since I’ve also been asked several times to give feedback on APIs designed by others, I think these doubts are quite common.

Luckily there’s a wealth of resources about the topic. In this post, I’ll go through my favorite writings that have helped me to understand how to apply REST, both in theory and in practise.

Basics

Do you have a solid understanding on technologies behind REST? If not, start by reading an article on CRUD. Continue with an explanation of HTTP, paying special attention to request methods and status codes. After this, you are ready to jump into more interesting stuff.

I really enjoyed the answers on the question “What exactly is RESTful programming?”. In a very concise way, it gives several examples on REST communication, relevant formats, relationship between CRUD and REST, principles behind HATEOAS, and explanation of Richardson Maturity Model.

Practical Advice

Okay, so that covered the essentials, but how about the practical details; Should we use plurals or singulars in URLs? How to map verbs into resources? What is a good abstraction level for resources? How search should be implemented with REST?

One set of answers is found from this excellent RESTful API design presentation. I especially appreciate their POST / GET / PUT / DELETE tables.

Since one opinion is never enough, here’s something more to read. The first article “Building an API: Best Practices” offers great advice in condensed format. The second one “Best Practices for Designing a Pragmatic RESTful API has some unique takes on pagination, formatting and data transfer optimization. Finally, read “Should RESTful API’s Include Relationships” to get additional insights on relationship modeling with REST.

Are You a RESTafarian?

Have you ever had a debate about the purity of your REST implementation? I have. Some people want to go all the way to HATEOAS while others settle somewhere closer to RPC.

In case you are interested about the topic, the authoritative source is the PhD thesis from Roy T. Fielding. You might also find his frustration on REST impurity interesting.

What does the community think about this? See an article about “How RESTful is your API and the related discussion. I personally tend to stick with level two on RMM.

Examples

Enough about theory! The following lists a set of known REST APIs to use as an example. Armed with the knowledge from the previous chapters, you can judge their quality yourself:

Further Reading

In case all that wasn’t too much for you, continue your journey with “Automated Documentation for REST APIs”. Or maybe you miss some real time functionalities in your web application? If that’s the case, then “Realtime APIs presentation” gives you some pointers forward.

Did I miss anything essential? If I did, then let me know. Good luck with your next REST API!