API Design roadmap

HTTP methods are the verbs of your web service, telling the server what action to perform on a resource. Using the correct method ensures your API behaves predictably and follows web standards.

For example, use GET to retrieve a user profile, and POST to create a brand new user account. When you send data to update an existing record, you use PUT or PATCH.

Getting these verbs right matters because it allows caches to work properly and helps other developers intuitively grasp how your endpoints function without reading endless documentation.

• Use GET to fetch data safely without changing state
• Use POST to create new resources
• Use PUT and PATCH for updating existing records
• Use DELETE to remove resources permanently

Status codes are three-digit numbers returned by the server to state the outcome of a request. They provide an instant signal about whether a client succeeded or encountered an issue.

For instance, returning a 200 OK confirms a successful retrieval, while a 404 Not Found means the requested item does not exist. If something breaks on your server, a 500 Internal Server Error alerts the client.

Clear status codes matter because they automate how client applications handle errors, saving developers hours of frustrating debugging.

• Codes in the 200 range mean success
• Codes in the 400 range indicate client errors
• Codes in the 500 range indicate server errors
• Always match the code accurately to the situation

HTTP headers are key-value pairs sent in requests and responses to pass extra metadata about the payload or connection. They dictate how data should be interpreted and handled.

An everyday example is the Content-Type header, which tells the client that the incoming response body is formatted as JSON rather than plain text. Other headers manage caching rules and authentication tokens.

Headers matter because they allow clients and servers to negotiate rules dynamically without cluttering the actual resource data you are trying to exchange.

• Use Content-Type to specify data formats
• Use Authorization headers to pass credentials safely
• Headers control caching and connection behavior
• Keep custom header names clear and consistent

Content negotiation is the mechanism that lets a client and server agree on the best data format for a response. It ensures your service can serve different audiences seamlessly.

Imagine a mobile app requesting data in JSON while an older reporting service needs XML. By inspecting the Accept header sent by the client, your server serves the exact format requested.

This matters for API longevity, enabling you to support multiple client types and future formats from a single endpoint without breaking existing integrations.

• Clients use the Accept header to request formats
• Servers respond with the matching Content-Type
• Return a 406 error if the requested format is unsupported
• JSON is the standard default for modern web APIs

Statelessness means the server does not store any session state about the client between requests. Every single request must contain all the context needed to process it successfully.

For example, instead of relying on a server session to remember who is logged in, every request must include an authentication token. The server validates the token fresh each time.

This matters because stateless APIs scale effortlessly. You can add more server instances behind a load balancer without worrying about which server holds a user's session data.

• Every request must contain complete authentication details
• Servers do not store client session data
• Improves scalability across multiple server instances
• Simplifies debugging and request tracing

Resource naming is the practice of structuring your URL paths around nouns rather than actions. Good names make your API endpoints self-explanatory and intuitive.

Instead of a confusing verb-based path like getActiveUsers, a RESTful design uses a clean noun plural like GET /users. You rely on the HTTP method to define the action.

Clean resource naming matters because it creates a predictable contract. Developers can guess endpoint structures correctly without constantly checking documentation.

• Use plural nouns for resource collections like /articles
• Avoid verbs in URL paths entirely
• Keep naming conventions consistent across the entire API
• Use lowercase letters and hyphens for readability

Resource hierarchies involve nesting related entities within your URL paths to reflect their real-world relationships. This shows clear connections between different data types.

For instance, if a user has many posts, the URL path /users/42/posts clearly shows you are fetching posts that belong specifically to user number 42.

Proper hierarchies matter because they mirror database relationships logically, making complex data structures easier to navigate and query from client applications.

• Nest sub-resources beneath their parent resource ID
• Keep nesting shallow to avoid overly long URLs
• Use top-level paths for independent resources
• Reflect real-world entity ownership clearly

Standardising error responses means returning a predictable JSON structure every time an API request fails. Instead of raw text or empty pages, clients receive clear diagnostic details.

When validation fails, your error payload might include an error code, a human-readable message, and a list of specific fields that failed validation checks.

Consistent error payloads matter because they allow frontend applications to display helpful alerts to users and handle specific failure scenarios programmatically.

• Use a consistent JSON schema for all errors
• Include a descriptive message for developers
• Provide machine-readable error codes
• List specific field errors for form validation failures

Pagination is the technique of breaking large collections of data into smaller, manageable chunks called pages. It prevents servers from crashing when asked to return millions of records at once.

Common approaches include offset-based pagination, which skips a set number of items, and cursor-based pagination, which points to a specific item ID for infinite scrolling.

Pagination matters for performance and user experience, ensuring fast response times and keeping memory usage low on both server and client devices.

• Use query parameters like limit and offset for basic splitting
• Consider cursor pagination for large or fast-changing datasets
• Include metadata like total count in responses
• Prevent clients from requesting excessively large page sizes

Filtering and sorting let clients use query parameters to narrow down and organise list results. They provide flexibility without requiring you to build dozens of separate endpoints.

For example, a client can request GET /products?status=active&sort=price_asc to retrieve only active items ordered from cheapest to most expensive.

This matters because it empowers clients to fetch precisely the data they need, reducing network bandwidth and avoiding heavy client-side data processing.

• Use query parameters for optional filters and sorts
• Document allowed filter fields clearly
• Sanitise inputs to prevent database injection risks
• Keep parameter names intuitive and consistent

Authentication verifies the identity of the client making requests to your API. It ensures that only authorised users and applications can access sensitive data and actions.

Common methods include API keys for server-to-server calls and JSON Web Tokens for user login sessions, passed securely in the request headers.

Authentication matters because open APIs invite abuse, data theft, and resource exhaustion. Securing your endpoints protects both your business and your users' privacy.

• Never expose sensitive data without authentication
• Use Bearer tokens or API keys in request headers
• Always enforce HTTPS to encrypt credentials in transit
• Implement proper token expiration and rotation

Rate limiting restricts the number of requests a client can make within a specific timeframe, such as one hundred requests per minute. It acts as a shield for your infrastructure.

When a client exceeds the limit, your server responds with a 429 Too Many Requests status code, often including headers showing when they can try again.

Rate limiting matters because it prevents malicious scraping, distributed denial-of-service attacks, and buggy client scripts from taking your entire system offline.

• Protect servers from abuse and accidental infinite loops
• Return HTTP 429 when limits are exceeded
• Use response headers to communicate remaining quota
• Apply stricter limits to unauthenticated endpoints

Versioning allows you to introduce breaking changes to your API without disrupting existing client applications. It ensures backward compatibility as your product evolves.

Common strategies include putting the version number in the URL path, such as /v1/users, or specifying it inside a custom request header.

Versioning matters because clients cannot always update their software instantly. Giving them time to migrate prevents sudden app crashes when you update your backend code.

• Include version numbers in URLs or headers
• Plan for backward compatibility before releasing
• Deprecate old versions gracefully with advance notice
• Keep the number of active versions to a minimum

OpenAPI is a standard specification format for describing REST APIs using JSON or YAML. It acts as a universal blueprint for your endpoints, request bodies, and responses.

Tools like Swagger UI read this specification file to generate interactive documentation pages where developers can test endpoints directly in their browser.

Writing OpenAPI specs matters because clear documentation is the hallmark of a great developer experience, reducing support questions and speeding up client integration.

• Use OpenAPI to describe endpoints in standard YAML or JSON
• Generate interactive documentation automatically using Swagger
• Keep your specification file updated alongside your code
• Validate requests and responses against your spec

GraphQL is a query language for APIs that lets clients request exact data shapes and nothing more. Instead of fixed server endpoints, a single endpoint accepts flexible queries.

If a mobile app only needs a user's name and email, it requests just those two fields, avoiding the over-fetching common in traditional REST APIs.

GraphQL matters because it empowers frontend developers to iterate quickly without waiting for backend teams to build new endpoints for every unique screen layout.

• Clients request exact data shapes in a single query
• Prevents over-fetching and under-fetching of data
• Uses a strongly typed schema for queries and mutations
• Operates via a single flexible POST endpoint

gRPC is a high-performance framework that allows microservices to communicate efficiently using protocol buffers and HTTP/2 transport.

Instead of reading human-readable JSON, services exchange compact binary data serialized from strongly typed interface definitions.

This matters for internal backend systems because binary serialization is much faster and uses less network bandwidth than JSON, making it ideal for high-throughput microservice architectures.

• Uses protocol buffers for compact binary serialization
• Built on HTTP/2 for multiplexed, fast communication
• Generates client and server code automatically
• Ideal for high-performance internal microservices