RESTful API Design Principles That Stand the Test of Time
REST API design has accumulated a set of battle-tested conventions over two decades of production use. The fundamentals haven't changed: use nouns for resource URLs not verbs, use HTTP methods semantically (GET for reads, POST for creates, PUT/PATCH for updates, DELETE for deletion), return appropriate HTTP status codes, and design for the consumer. The APIs that are a pleasure to work with in 2026 follow these fundamentals rigorously and add modern practices around versioning, authentication, documentation, and error responses.
URL Structure and Resource Naming
Resource URLs should be nouns in the plural form: /users not /user, /products not /product, /templates not /template. Nested resources use the parent path: /users/{id}/posts for a specific user's posts. Query parameters handle filtering, sorting, and pagination: /products?category=dashboard&sort=price&order=asc&page=2&limit=20. Avoid query parameters for resources that should have permanent URLs — /products/featured is preferable to /products?featured=true when the featured collection is a stable, linkable resource. Keep URLs lowercase, use hyphens not underscores, and avoid file extensions in URLs.
HTTP Status Codes: Use Them Correctly
The most common mistake in REST API design is returning 200 OK for error responses. Use 200 for successful reads, 201 for successful creates (with Location header pointing to the new resource), 204 for successful deletes with no body, 400 for client errors with validation details in the body, 401 for unauthenticated (no valid credentials), 403 for unauthorized (credentials valid but insufficient permissions), 404 for resources that don't exist, 422 for validation errors with field-level details, 429 for rate limit exceeded with Retry-After header, and 500 for server errors that the client cannot resolve.
Authentication: JWT vs API Keys vs OAuth
Choose the authentication mechanism based on the API consumer. Public APIs used by third-party developers: API keys for simple cases, OAuth 2.0 with PKCE for user-scoped access. Internal APIs consumed by your own frontend: JWT with short expiry (15 minutes) and refresh tokens stored in httpOnly cookies. Machine-to-machine APIs: OAuth 2.0 client credentials flow or mTLS. API keys should be long (32+ characters), randomly generated, hashed before storage, and scoped to specific permissions. JWTs should be signed with RS256 (asymmetric) for APIs with multiple verification endpoints, HS256 for single-service tokens.
Error Response Format
Consistent error responses are critical for API usability. Define a standard error object and use it everywhere: include an error code (machine-readable string like RESOURCE_NOT_FOUND), a human-readable message, optional details array for validation errors with field-level information, and a request ID for tracing. Never expose stack traces, internal error messages, or database errors in production API responses. The error code should be stable across API versions so clients can write conditional logic against it.
Pagination, Filtering, and Sorting
Cursor-based pagination is more reliable than offset pagination for large datasets — it doesn't miss items when data is inserted between page loads and performs better on large tables. Return a cursor pointing to the last item in the response, and clients send cursor=abc123 to get the next page. For filtering, use the Django-style field__lookup pattern or GraphQL-style filter objects for complex queries. Always return total count and next/previous links in paginated responses. ProofMatcher's API templates include pre-built pagination and filtering patterns for Django REST Framework — download free at proofmatcher.com.
Originally published at https://proofmatcher.com/blogs/api-design-best-practices-2026
Top comments (0)