REST API design best practices

An API is a user interface for developers. A consistent, predictable design means fewer support tickets and faster integrations. These conventions are widely followed across public APIs.

Resources and URLs

Model your API around nouns (resources) and let HTTP methods supply the verbs.

Action	Good	Avoid
List orders	GET /v1/orders	GET /v1/getAllOrders
Get one order	GET /v1/orders/9812	GET /v1/order?id=9812
Create	POST /v1/orders	POST /v1/createOrder
Update part	PATCH /v1/orders/9812	POST /v1/updateOrder
Order's items	GET /v1/orders/9812/items	GET /v1/items?order=9812&type=child
Cancel (an action)	POST /v1/orders/9812/cancel	GET /v1/orders/9812?cancel=true

Use plural nouns, lowercase and hyphens (/gst-invoices), and keep nesting to one level.

Consistent JSON

Pick conventions and apply them everywhere:

{
  "id": 9812,
  "customer_id": 42,
  "status": "shipped",
  "total": "1798.00",
  "currency": "INR",
  "created_at": "2026-09-14T10:32:05+05:30",
  "items": [
    {"sku": "KURTA-M-BLU", "qty": 2, "unit_price": "899.00"}
  ]
}

• One naming style for keys (snake_case or camelCase) across the entire API.
• Dates in ISO 8601 with a timezone offset.
• Money as a string or integer paise, never a float, plus an explicit currency.
• Enumerations as readable strings ("shipped"), not magic numbers.
• Return the created or updated resource so clients don't need a second request.

Filtering, sorting and field selection

Use query parameters: GET /v1/products?category=silk&min_price=2000&sort=-price&fields=id,name,price. A leading minus for descending sort is a common and readable convention.

Error responses

Errors deserve the same care as successes. Use the right status code and a predictable body:

{
  "error": {
    "code": "validation_error",
    "message": "Some fields are invalid.",
    "details": [
      {"field": "pincode", "issue": "Must be 6 digits."}
    ],
    "request_id": "req_7Hc2kQ"
  }
}

A machine-readable code lets clients branch on errors; message is for humans; request_id helps your support team find the log line. Never leak stack traces or SQL in production errors.

Versioning and evolution

Put the major version in the path (/v1/) or a header. Within a version, only make additive changes: new optional fields and new endpoints are fine; renaming or removing fields breaks clients. When you must break, release /v2/, announce a deprecation date and send a Deprecation or Sunset header on the old version.

Documentation

Describe your API with an OpenAPI specification. Tools like Swagger UI and Redoc turn it into interactive docs, and frameworks such as FastAPI or drf-spectacular generate it from code.

Key takeaways

• Nouns in URLs, verbs from HTTP methods.
• Consistent naming, ISO dates, safe money types.
• Structured errors with codes and request IDs.
• Version explicitly and evolve additively.