Best Practices for Consistent Backend API Design
This guide presents a concise set of best‑practice rules for designing consistent, RESTful backend APIs—including naming conventions, versioning, pagination, security, monitoring, and error handling—to improve developer experience and maintainability across microservice architectures.
In the world of micro‑services, a well‑designed backend API is essential; this article outlines practical rules to achieve consistency and clarity.
Terminology : a resource is a piece of data (e.g., user), a collection groups resources (e.g., user list), and a URL identifies a resource or collection.
1. Use kebab‑case for URLs . Wrong examples: /systemOrders or /system_orders . Correct: /system-orders .
2. Use camelCase for parameters . Wrong: /system-orders/{order_id} or /system-orders/{OrderId} . Correct: /system-orders/{orderId} .
3. Name collections with plural nouns . Wrong: GET /user or GET /User . Correct: GET /users .
4. URLs start with a collection and end with an identifier . Bad: GET /shops/:shopId/category/:categoryId/price . Good: GET /shops/:shopId/category/:categoryId .
5. Keep verbs out of resource URLs . Use HTTP methods instead. Bad: POST /updateuser/{userId} . Good: PUT /user/{userId} .
6. Use verbs only for non‑resource actions . Example: POST /alarm/245743/resend to trigger a specific operation.
7. JSON property names should be camelCase . Bad: { "user_name": "Mohammad Faisal", "user_id": "1" } . Good: { "userName": "Mohammad Faisal", "userId": "1" } .
8. Provide monitoring endpoints : /health (respond 200 OK), /version (return version), /metrics (expose metrics). Additional optional endpoints: /debug , /status .
9. Avoid using raw table names as resources . Bad: product_order . Good: product-orders .
10. Use API design tools such as API Blueprint ( https://apiblueprint.org/ ) and Swagger ( https://swagger.io/ ) to generate clear documentation.
11. Apply simple ordinal versioning (e.g., v1 , v2 ) and place the version segment at the leftmost part of the path: http://api.domain.com/v1/shops/3/products .
12. Include total resource count in list responses . Example bad response: { "users": [ ... ] } . Good response: { "users": [ ... ], "total": 34 } .
13. Accept limit and offset parameters for pagination . Example: GET /shops?offset=5&limit=5 .
14. Provide a fields query parameter to limit returned fields . Example: GET /shops?fields=id,name,address,contact .
15. Never place authentication tokens in URLs ; instead use the Authorization: Bearer <token> header.
16. Validate the Content‑Type header and explicitly require application/json when appropriate.
17. Map CRUD operations to HTTP methods : GET (read), POST (create), PUT (replace), PATCH (partial update), DELETE (remove).
18. Use relationships in nested resource URLs (e.g., GET /shops/2/products , GET /shops/2/products/31 , DELETE /shops/2/products/31 , POST /shops ).
19. Enable CORS for all public APIs and consider allowing "*" origins with OAuth‑protected access.
20. Enforce HTTPS (TLS) on every endpoint, callback URL, push notification endpoint, and webhook.
21. Return proper error codes : use 4xx for client‑side errors and consider aggregating validation issues in a single response.
22. Golden rules : prefer flat over nested structures, simplicity over complexity, strings over numbers, and consistency over custom solutions.
Following these guidelines will help you design clean, maintainable, and user‑friendly APIs.
IT Architects Alliance
Discussion and exchange on system, internet, large‑scale distributed, high‑availability, and high‑performance architectures, as well as big data, machine learning, AI, and architecture adjustments with internet technologies. Includes real‑world large‑scale architecture case studies. Open to architects who have ideas and enjoy sharing.
How this landed with the community
Was this worth your time?
0 Comments
Thoughtful readers leave field notes, pushback, and hard-won operational detail here.