Mastering Consistent API Design: 22 Essential Best Practices

Key Terminology

API design follows the resource‑oriented principle: a resource (e.g., user), a collection of resources (e.g., users), and a URL that identifies them (e.g., /user).

1. Use kebab‑case for URLs

URLs should be lowercase words separated by hyphens.

/system-orders

2. Use camelCase for parameters

Parameter names in the path should follow camelCase.

/system-orders/{orderId}

3. Use plural nouns for collections

Collections are named with plural nouns.

GET /users

4. URLs start with a collection and end with an identifier

Keep URLs simple and resource‑centric.

GET /shops/3/products/31

5. Keep verbs out of resource URLs

Use HTTP methods to express actions, not verbs in the path.

PUT /user/{userId}

6. Use verbs only for non‑resource URLs

When an endpoint performs a single operation, a verb is acceptable.

POST /alarm/245743/resend

7. Use camelCase for JSON properties

JSON field names should be camelCase.

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

8. Monitoring endpoints

Implement health, version, and metrics endpoints. /health – respond with HTTP 200 OK. /version – return the API version. /metrics – expose performance metrics.

9. Avoid using table names as resource names

Prefer domain‑oriented names.

product-orders

10. Use API design tools

Tools such as API Blueprint and Swagger help produce clear documentation.

11. Use simple numeric versioning

Place the version as a left‑most path segment.

http://api.domain.com/v1/shops/3/products

12. Include total resource count in responses

When returning a list, add a total field.

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

13. Accept limit and offset parameters

Support pagination for list endpoints.

GET /shops?offset=5&limit=5

14. Provide a fields query parameter

Allow callers to request only needed fields.

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

15. Do not put authentication tokens in URLs

Pass tokens via headers instead.

Authorization: Bearer xxxxxx

16. Validate content type

Never assume a request's content type; enforce it explicitly.

Content-Type: application/json

17. Use proper HTTP methods for CRUD

GET – retrieve a representation.

POST – create a new resource.

PUT – replace an existing resource.

PATCH – partially update a resource.

DELETE – remove a resource.

18. Use relationships in nested resource URLs

Express parent‑child relations clearly. GET /shops/2/products – list products of shop 2. GET /shops/2/products/31 – get product 31 of shop 2. POST /shops – create a new shop.

19. Enable CORS for public APIs

Allow cross‑origin requests, preferably with a wildcard origin and OAuth‑based authorization.

20. Enforce HTTPS

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

21. Error handling

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

22. Golden rules

Prefer flat over nested structures.

Simplicity beats complexity.

Use strings rather than numbers where possible.

Consistency outweighs custom solutions.

Following these practices helps create clean, maintainable, and user‑friendly APIs.