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.
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.
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?
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:
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!