Previously
We were talking about REST API and the most important trait of REST, Statelessness. You can read it here, if you didn’t have opportunity for it. Today’s topic is uniform interface, it’s mostly about look and feel of our endpoints. Some people may say that it’s not important, these people didn’t work with poorly written API. You need to remember that APIs are created for clients, if your API is hard to use, too complex, inconsistent or unpredictable, client will not like to consume it, therefore you’ll not get any profit.
Now to the point
Knowing responsibilities of each verb was prerequisite for real thing. I said that your API should be consistent, by this I mean that client should know what will be result of calling one of endpoints. Consider table below.
POST (create)
/students –> Create a new student
/students/2 –> Method not allowed (405)
GET (read)
/students –> Returns a list of students
/students/2 –> Returns a specific student
PUT (update)
/students–> Bulk update of students
/students/2 –> Updates a specific student
DELETE (delete)
/students–> Delete all students
/students/2 –> Deletes a specific student
Now you know what I mean. These are default action for every verb. Clients with experience in using API will assume that your Get action will load data from API and Delete remove something.
Self-descriptive messages
Behind this hides simple statement, every response from API should contain enough information, so client may know what’s happening. By that I mean, your client should be able to update resource when you return it to him. Browser should know if it needs to parse JSON or XML. Finally client should know if his action succeeded of failed.
In my opinion the most important is to return descriptive messages in case of errors. As a client I would like to know what happened. Did I break something or it was something else. There is more, in some cases user can fix his problem by himself. Consider form with required Name. How your client can know that field is required if your response isn’t descriptive? Well he can’t.
Real life example
That was trivial example, but here’s something from real life. I was working with API which returned documents as a text, one time I couldn’t get my document, there wasn’t any errors. Everything was 200 OK. I started debugging, and checked if document is even there. To my amazement document was there I tried to open it, and then mystery was solved. Document was encrypted, API couldn’t open it and exception was swallowed so API returned 200.
There were couple of problems. First of all, ignored exception and second no information from API. It is one of the first things you should learn, don’t you ever swallow exceptions, it’s never good idea and a lot of times it makes problems. Someone prepared to catch exception and return error message, but he forgot to finish. Here’s second tip, finish what you’ve started or there is chance that you forget to finish your work, like someone from above.
Optional, but nice to know
HATEOAS, behind that cool looking name is Hypermedia as the engine of application state, from name you can guess that it’s about application state. It is great way to “remember” state without storing it on API.
Every time you send response you can add additional fields like links to next document on the list, or link to previous document, or even next and previous page. Now your client can ask for next document and still you’re following REST, because your API will get every information it needs by using url prepared by your own hands.
Unfortunately HATEOAS aren’t used too often. It’s because of clients. It’s additional work for you to prepare HATEOAS, but it’s worth your time, because who knows better than you how to use your API. Additionally everything can be written once and made generic. You can speed up the work for your client. There is one “but” thou. Your client have to switch thinking about how to use API. Instead of copying your urls from swagger or another documentation client would need to trust you and let you pass him endpoints he need to use.
It’s not common way of using APIs, that’s why clients aren’t familiar with HATEOAS and that’s why there isn’t too much APIs that have it. I have it on my list, so I’ll write post about HATEOAS spike later in future.
Outro
Now you should know what to look for during creating you REST API. Make it as easy and predictable as possible, and help your clients solve errors during work with API by returning information about error.
As always I encourage you to comment or talk to me if you have questions or suggestions. Additionally I’d like to share with some blog posts that helped me a lot when I was starting with Web API. Next time we’ll finish API basics with Status Codes and then we’ll go straight to coding 🙂
http://blog.restcase.com/7-rules-for-rest-api-uri-design
https://blog.mwaysolutions.com/2014/06/05/10-best-practices-for-better-restful-api/