I was looking for information about REST API (Representational State Transfer), I came across on this blog “How to design a REST API”. I found this blog to be useful, simple and has examples include. The blog and Quick Reference Card divided into 4 main sections.
First section is general concept, one of the main goals of API should be able to reach out to as many developers as possible. That mean API needs to be self-describing and simple. In security, how important is Oauth to manage Authorization, that being used by many companies. Which use the token system, without showing the real Authorization. API domain names are also important that need to be clear and straightforward.
Second is URIs, RESTful API use different approach using concrete names and not action verbs. API needs to have case consistency and plurals to make the structure clear. Versioning should be mandatory in the URL. Crud-like operations explain how HTTP Verb uses (GET, POST, PUT, DELETE) as CRUD action (READ, CREATE, UPDATE/CREATE, DELETE) with examples.
Third section is about query strings, combined API design such as filters, pagination, partial responses and sort to give query better result, also to optimize bandwidth. We can use a range query parameter. API response should contain Link, Content-Range, Accept-Range.
Finally, the Status Codes, developers will come across this. We need to return error for common case, which everybody understands. The HTTP return codes is which highly recommended for this. First case is success, which mean the API accepted the request. Second is client error, when client requests but API couldn’t accept, reasons such as 401 Unauthorized, 405 Method Not Allowed … There also Server Error, where the request is correct, but a problem occurred on the server. System will return as Status 500 Internal Server Error. This return is somewhat common, the client cannot do anything about that.
I like this summary of practices, its cover a large amount of good detailed references. The Quick Reference Card is clear and always have good examples next to it. I find that much easier to understand, since they use examples from popular sites such as Google, Facebook, Twitter. Everyone is familiar with those companies and based on the instruction, that make the examples are more reliable.