Most REST APIs don’t fail because they broke some technical rule. They fail because developers can’t predict how they behave.
Here are 8 patterns that fix thatand make your API easier to understand, integrate, and maintain.
1. Design Around Resources, Not Actions
A common mistake: endpoints like getUsers, createOrder, deleteProduct.
They look fine at first. But the URL is now describing the action, while HTTP already does that job.
The cleaner fix is, treat users, orders, and products as resources. Let GET, POST, and DELETE describe the operation.
GET /orders -> list orders POST /orders -> create an order GET /orders/{id} -> retrieve an order PUT /orders/{id} -> replace an order DELETE /orders/{id} -> delete an order
This scales better too. The same resource supports multiple operations without inventing a new URL for each one.
The rule: the URL identifies the resource. The HTTP method describes what you’re doing to it.
I think this is a seemingly small but important point that sets this article apart from so many others on this subject. Often articles like this only describe the simple cases of the obvious resources, which often comes out as relatively simple…
