Best Practices for Designing Consistent Backend APIs

Introduction

The author, a senior architect, shares practical rules to avoid common pitfalls when designing APIs in a micro‑service environment, aiming for simplicity, consistency, and a good developer experience.

1. Use kebab‑case for URLs

Correct: /system-orders

Incorrect: /systemOrders or /system_orders

2. Use camelCase for parameters

Correct: /system-orders/{orderId}

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

3. Use plural nouns for collections

Correct: GET /users

Incorrect: GET /user or GET /User

4. URL should start with a collection and end with an identifier

Correct: GET /shops/3/products/31

Incorrect: GET /shops/:shopId/category/:categoryId/price

5. Keep verbs out of resource URLs

Correct: PUT /user/{userId}

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

6. Use verbs only for non‑resource actions

Example: POST /alarm/245743/resend

7. JSON property names should be camelCase

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

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

8. Monitoring endpoints

Implement /health (200 OK), /version (return version), and /metrics (expose metrics). Optional: /debug , /status .

9. Avoid using raw table names as resources

Correct: /product-orders

Incorrect: /product_order

10. Use API design tools

Examples: API Blueprint (https://apiblueprint.org/), Swagger (https://swagger.io/).

11. Simple numeric versioning

Use URLs like http://api.domain.com/v1/shops/3/products .

12. Include total count in list responses

Correct response: { "users": [ ... ], "total": 34 }

13. Accept limit and offset for pagination

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

14. Provide a fields query parameter to limit returned attributes

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

15. Do not put authentication tokens in URLs

Instead send them in headers: Authorization: Bearer xxxxxx

16. Validate Content‑Type

Always check and enforce Content-Type: application/json (or other expected types).

17. Map CRUD operations to HTTP methods

GET – retrieve

POST – create

PUT – replace

PATCH – partial update

DELETE – delete

18. Use relationships in nested URLs

Examples: GET /shops/2/products , GET /shops/2/products/31 , DELETE /shops/2/products/31 , POST /shops .

19. Enable CORS for public APIs

Allow "*" origins with proper OAuth token validation.

20. Enforce HTTPS everywhere

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

21. Proper error handling

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

22. Golden rules

Flat > nested

Simplicity > complexity

Strings > numbers

Consistency > custom

Following these rules helps create clean, maintainable APIs.