Yesterday I downloaded the APIs for DUMMIES ebook. I really liked this book because it in 2 or 3 hours you can read and learn about best practices of REST api best practices.
This is just what we are doing right now and I found many useful and interesting ideas and suggestions.
I like this kind of book: they are not academic, are free (!) and you can learn about best practice without to spend hours to read and to understand the reason why these are best practices.
Without explanations or more details, for sure “you have to believe” that few pages are correct but, in this case, apigee name guarantee all the readers.
In just 36 pages, they are condensed many important points, like:
- Keep your base URL simple and intuitive
- Use two base URLs per resource.
- Keep verbs out of your base URLs. Use verbs just for responses that don’t involve resources (like calculate, language translation, etc)
- Use HTTP verbs to operate on the collections and elements.
- (…) keep your API intuitive by simplifying the associations between resources,
- and sweeping parameters and other complexities under the rug of the HTTP question
- Regarding error and status code: use HTTP status code but not too much…. Start by using the following 3 codes. If you need more, add them. But you shouldn’t need to go beyond 8. • 200 – OK • 400 – Bad Request • 500 – Internal Server Error
- If you’re not comfortable reducing all your error conditions to these 3, try picking among these additional 5: • 201 – Created • 304 – Not Modified • 404 – Not Found• 401 – Unauthorized • 403 – Forbidden
- Never release an API without a version and make the version mandatory.
- Support partial response by adding optional fields in a comma delimited list.
- Use limit and offset to make it easy for developers to paginate objects.
- Consolidate all API requests under one API subdomain.
- The API Façade Pattern
So, if you have a couple of hours and if you like application development tools and techniques, you have to read this ebook!