Best Practices for Consistent Backend API Design

Introduction

In the world of micro‑services, consistent backend API design is indispensable. This article presents a short, sweet list of best‑practice rules.

Terminology

API design follows the "resource‑oriented design" principle, where a resource is a piece of data (e.g., a user), a collection is a group of resources (e.g., user list), and a URL identifies the location of a resource or collection (e.g., /user ).

1. Use kebab‑case for URLs

Bad: /systemOrders or /system_orders

Good: /system-orders

2. Use camelCase for parameters

Bad: /system-orders/{order_id} or /system-orders/{OrderId}

Good: /system-orders/{orderId}

3. Use plural names for collections

Bad: GET /user or GET /User

Good: GET /users

4. URL starts with a collection and ends with an identifier

Bad: GET /shops/:shopId/category/:categoryId/price (points to an attribute)

Good: GET /shops/:shopId/ or GET /category/:categoryId

5. Keep verbs out of resource URLs

Bad: POST /updateuser/{userId} or GET /getusers

Good: PUT /user/{userId}

6. Use verbs only for non‑resource actions

Example: POST /alarm/245743/resend

7. JSON property names in camelCase

Bad: { user_name: "Mohammad Faisal", user_id: "1" }

Good: { userName: "Mohammad Faisal", userId: "1" }

8. Monitoring endpoints

Implement /health (respond 200 OK), /version (return version), and /metrics (provide metrics such as average response time). /debug and /status are also recommended.

9. Avoid using raw table names as resources

Bad: product_order

Good: product-orders

10. Use API design tools

Good tools include API Blueprint ( https://apiblueprint.org/ ) and Swagger ( https://swagger.io/ ).

11. Use simple numeric versioning

Version URLs should be like http://api.domain.com/v1/shops/3/products .

12. Include total resource count in responses

Bad response: { users: [ ... ] }

Good response: { users: [ ... ], total: 34 }

13. Accept limit and offset parameters

Example: GET /shops?offset=5&limit=5

14. Provide fields query parameter

Example: GET /shops?fields=id,name,address,contact

15. Do not put authentication tokens in URLs

Bad: GET /shops/123?token=some_kind_of_authenticaiton_token

Good: send via header, e.g., Authorization: Bearer xxxxxx, Extra yyyyy

16. Validate content‑type

Always check the request's Content-Type . Prefer application/json for JSON payloads.

17. Use proper HTTP methods for CRUD

GET – retrieve, POST – create, PUT – replace, PATCH – partial update, DELETE – remove.

18. Use relationships in nested resource URLs

GET /shops/2/products – list products of shop 2

GET /shops/2/products/31 – details of product 31 in shop 2

DELETE /shops/2/products/31 – delete that product

PUT /shops/2/products/31 – update that product

POST /shops – create a new shop

19. Support CORS for public APIs

Allow "*" origins and enforce OAuth token authorization.

20. Enforce HTTPS everywhere

All endpoints, callbacks, push notifications, and webhooks must use TLS.

21. Error handling

Return 4xx codes for client errors and include detailed validation messages when possible.

22. Golden rules

Flat is better than nested.

Simplicity beats complexity.

Strings are preferred over numbers.

Consistency beats customization.

That’s it – congratulations if you made it this far, and happy coding!