This article is about some of the significate trends in API design. Since REST is not strict standard it becomes very big appetite to use design patterns.
1. Always use Nouns not Verbs
Keep API simple. Simple to read and simple to understand. Think API as a way to browse the business catalog. Use HTTP methods to perform actions. Always start from collections to a specific item.
GET all books — — → /books
Get a specific book — — — → /books/1234
2. Avoid Abstract Nouns
Abstraction is very good at hiding the complexity but we should always use the concrete nouns. It becomes very hard to understand what we can do with more abstract API. For example, if we use the /items, it is not self-explanatory. Instead, use the /books, pens/ etc. The level of abstraction is very specific to the application. Always draw the business model before starting API design.
3. Keep association simple
The application can be complex. One resource can have a relationship with another resource.
This relationship can go 4 to 5 levels and more, going deeper add complexity. try to keep URL smaller.
4. Use the Query parameter(?) for resource states
The resources can have various states. For example, /orders/ can have ordered, shipped, arriving, delivered. HTTP provides limited methods. Use the ? to browse/filter the resources.
5. Make API versioning mandatory
API can change in future, it should not break the existing consumer. always use the versioning while designing API
6. Expose the Business not technology
Never expose the internal technical jargon. An application can have many internal objects, these objects are well understood by one team but internal object won’t make sense to API consumer team.
7. Use HTTP status code for Error Handling
8. Use stateless session management