Mastering Consistent API Design: 22 Essential Best Practices

URL conventions

Use kebab‑case for path segments, e.g. /system-orders. Use camelCase for path and query parameters, e.g. /system-orders/{orderId}. Collections should be plural nouns, e.g. GET /users. URLs should start with a collection and end with an identifier: /resource/{id}. Do not embed attributes in the path; separate resources into their own endpoints.

Verb usage

Do not place verbs in resource URLs; use HTTP methods to express actions (e.g. PUT /user/{userId} for update). Verbs are allowed only for non‑resource operations, such as POST /alarm/245743/resend.

JSON naming

Use camelCase for JSON property names, e.g. { "userName": "John", "userId": "1" }.

Monitoring endpoints

/health – returns 200 OK.

/version – returns API version.

/metrics – exposes performance metrics (average response time, etc.).

Optional: /debug , /status .

Resource naming

Avoid using raw table names; prefer domain‑oriented names such as product-orders instead of product_order.

API design tools

Document APIs with tools such as API Blueprint (https://apiblueprint.org/) or Swagger (https://swagger.io/).

Versioning

Prefix APIs with a simple numeric version, e.g. /v1: http://api.example.com/v1/shops/3/products.

List responses

Include a total field indicating the total number of resources:

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

Pagination

Support limit and offset query parameters, e.g. GET /shops?offset=5&limit=5.

Field selection

Allow callers to request a subset of fields with a fields parameter, e.g. GET /shops?fields=id,name,address,contact.

Authentication

Never place tokens in URLs. Pass credentials via the Authorization header, e.g. Authorization: Bearer xxxxxx. Tokens should be short‑lived.

Content‑type validation

Reject unexpected content types; for JSON APIs require Content-Type: application/json.

CRUD mapping

GET – retrieve resources.

POST – create resources.

PUT – replace resources.

PATCH – partially update resources.

DELETE – remove resources.

Nested resources

Express relationships in URLs, e.g.:

GET /shops/2/products

GET /shops/2/products/31

DELETE /shops/2/products/31

PUT /shops/2/products/31

POST /shops

CORS

Enable CORS for public APIs, allowing * origins and enforcing OAuth token validation.

Security

Enforce HTTPS on all endpoints, callbacks, webhooks and push notifications.

Error handling

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

Golden rules

Prefer flat structures over deep nesting.

Simplicity beats complexity.

Use strings for identifiers.

Maintain consistency across the API.