squirrelworks
The Gold Rule: In REST, the URL identifies the resource, while the HTTP method identifies the action. Never put verbs in your URIs.
To create a truly RESTful interface, your endpoints should always be named after the resources they represent. Use plural nouns to keep the API intuitive. For example, instead of /getUsers (which is an RPC style), use /users. This allows a single endpoint to handle multiple actions based on the HTTP verb used, such as fetching a list or creating a new entry.
/getAllOrders/updateOrder?id=5/deleteOrder/10GET /ordersPUT /orders/5DELETE /orders/10When resources are related, your URL structure should reflect that hierarchy. This makes the API self-documenting and easy for developers to navigate without referring back to documentation constantly.
If you want to fetch all comments for a specific blog post, the URI should flow from the parent to the child: /posts/001/comments. This clearly indicates that the comments are scoped to that specific post. Avoid going more than two or three levels deep (e.g., /users/1/posts/5/comments/10/author), as this makes the URI overly complex and difficult to maintain.
A common mistake is creating unique endpoints for different views of the same data (e.g., /getActiveUsers). In REST, you should use the base resource and modify the result using Query Parameters.
GET /users?status=activeGET /products?sort=price_descGET /orders?page=2&limit=50By keeping the base URI clean, you allow the client to define exactly what data it needs. This reduces the "Information Density" overhead on the server and makes the API much more flexible for different frontend requirements, such as mobile apps vs. desktop dashboards.
Proper REST design uses the built-in "language" of the web to communicate results. Never return a 200 OK if an error occurred.
| Method | Standard Path | Success Code | Technical Result |
|---|---|---|---|
| GET | /resources |
200 OK | Returns a list or single object. |
| POST | /resources |
201 Created | Creates a new record. |
| PUT | /resources/id |
200 OK | Updates an existing record entirely. |
| PATCH | /resources/id |
200 OK | Updates specific fields only. |
| DELETE | /resources/id |
204 No Content | Removes the record successfully. |
| ANY | Invalid Path | 404 Not Found | The URI does not exist. |
| ANY | Auth Failure | 401 Unauthorized | Client lacks valid credentials. |
As your Squirrelworks projects grow, your data structures will inevitably change. To avoid breaking existing clients (like older versions of your mobile app or external integrations), you must version your API from day one.
The industry standard is to include the version in the URL path: /v1/users. This provides a clear "Contract" between the server and the client. When you need to make a "breaking change" (like renaming a JSON field), you deploy /v2/, allowing legacy clients to continue functioning on the v1 endpoint until they are ready to migrate. This maintains the "High Availability" state we strive for in enterprise-grade architecture.
Design Guide Complete. ← Return to Architecture Comparison