Best Practices for Designing Consistent RESTful APIs

Designing a consistent and maintainable API is essential in a micro‑service world; this guide outlines practical best‑practice rules to achieve that goal.

Terminology

Resource – a single data entity, e.g., /user

Collection – a set of resources, e.g., /users

URL – the address that identifies a resource or collection.

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. URLs 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

Incorrect: POST /updateuser/{userId} Correct: use HTTP methods (e.g., 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

Incorrect: { "user_name": "...", "user_id": "..." } Correct: { "userName": "...", "userId": "..." }

8. Provide monitoring endpoints

Implement /health (200 OK), /version (returns version), and /metrics (exposes performance metrics); optionally /debug and /status .

9. Avoid using raw table names as resources

Incorrect: product_order Correct: product-orders

10. Use API design tools for documentation

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

11. Use simple numeric versioning

Prefix URLs with /v1/ , /v2/ , etc., e.g., http://api.domain.com/v1/shops/3/products .

12. Include total count in list responses

Correct response example: { "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 fields

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

15. Never place authentication tokens in URLs

Use headers instead, e.g., Authorization: Bearer xxxxxx .

16. Validate the Content‑Type header

Accept only expected types, such as Content-Type: application/json .

17. Map CRUD operations to HTTP methods

GET – retrieve

POST – create

PUT – replace

PATCH – partial update

DELETE – remove

18. Express 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 enforcement.

20. Enforce HTTPS on all endpoints and callbacks.

21. Return appropriate 4xx error codes for client‑side failures and aggregate validation errors.

22. Follow the “golden rules” for API design

Flat is better than nested.

Simplicity beats complexity.

Strings over numbers when possible.

Consistency over customization.

By adhering to these guidelines, developers can create APIs that are easy to understand, use, and evolve.