ThisCalculator

Everyday

REST API Design: Best Practices & Examples

Updated · Standard formula, shown below

Average pace 5.00 min/km
Average speed
12.00 km/h
Result
Finish time
50 min
You entered
Distance
10 km
You entered

REST API design is the practice of building web services that follow the Representational State Transfer (REST) architectural style, using HTTP methods and URIs to expose resources. This article explains the core principles, common conventions, and practical patterns for designing APIs that are intuitive, reliable, and easy to maintain.

What Is REST?

REST (Representational State Transfer) is an architectural style introduced by Roy Fielding in his 2000 doctoral dissertation. It defines a set of constraints for building distributed systems, most commonly applied to web APIs. The key idea is that a service exposes resources (e.g., users, orders, products) identified by URIs, and clients interact with them using standard HTTP methods: GET, POST, PUT, PATCH, DELETE.

REST is not a protocol or a standard—it is a style. An API can be “more RESTful” or “less RESTful” depending on how well it adheres to the constraints. The most important constraints are:

  • Client-server architecture – the client and server evolve independently.
  • Statelessness – each request contains all the information needed to process it; the server does not store client context between requests.
  • Cacheability – responses must indicate whether they can be cached or not.
  • Layered system – the client cannot tell whether it is connected directly to the server or through intermediaries.
  • Uniform interface – a consistent way to identify resources, manipulate them, and describe themselves.

Core Principles of REST API Design

In practice, designing a REST API means making decisions about resource modeling, HTTP methods, status codes, and data formats. The most widely accepted principles are:

  • Use nouns, not verbs – URIs should represent resources: /users, /orders/123. Avoid actions like /getUser or /createOrder.
  • Use HTTP methods for actions – GET for retrieval, POST for creation, PUT for full update, PATCH for partial update, DELETE for removal.
  • Use plural nouns for collections – /users (collection) and /users/123 (single item) are more consistent than mixing singular and plural.
  • Use HTTP status codes correctly – 200 for success, 201 for created, 204 for no content, 400 for bad request, 401 for unauthorized, 403 for forbidden, 404 for not found, 500 for server error.
  • Use JSON or XML as the primary format – JSON is the de facto standard for modern APIs.
  • Version your API – either in the URI (/v1/users) or via a header (e.g., Accept: application/vnd.example.v1+json).

How to Design a REST API (Step by Step)

Designing a REST API from scratch involves several steps. Here is a practical workflow:

  1. Identify the resources – List the main entities your system manages. For an e-commerce system: customers, products, orders, payments.
  2. Define the relationships – How do resources relate? An order belongs to a customer; an order has many items.
  3. Design the endpoints – For each resource, create a collection and an item endpoint. Example: GET /orders and GET /orders/{id}.
  4. Decide on the methods – For each endpoint, determine which HTTP methods are allowed. For a collection: GET (list), POST (create). For an item: GET (retrieve), PUT/PATCH (update), DELETE (remove).
  5. Define the response format – Use a consistent JSON structure. Include an id field, timestamps, and hypermedia links if following HATEOAS.
  6. Plan for filtering, sorting, pagination – Use query parameters: ?limit=10&offset=20, ?sort=created_at, ?status=active.
  7. Handle errors – Return a consistent error object with a code, message, and details.

Common Mistakes in REST API Design

Even experienced developers make recurring mistakes. Here are the most common ones and how to avoid them:

  • Using verbs in URIs – /getAllUsers is not RESTful; use GET /users.
  • Ignoring HTTP status codes – Returning 200 with an error body is confusing. Use 400 for client errors, 404 for missing resources, 500 for server failures.
  • Not versioning – When you change the API, clients break. Version from day one.
  • Over- or under-fetching data – Returning the entire user object when only the name is needed wastes bandwidth. Use sparse fieldsets (e.g., ?fields=name,email).
  • Using a single endpoint for everything – POST /api with an action parameter is an anti-pattern. It hides the resource structure.
  • Not handling concurrency – If two clients update the same resource, you need a way to detect conflicts. Use ETags or version numbers.

REST vs. Other API Styles

REST is not the only way to build APIs. Comparing it with alternatives helps you choose the right tool:

  • SOAP – A protocol with strict standards, XML-only, and built-in error handling. Heavier and more complex than REST. Often used in enterprise and financial systems.
  • GraphQL – A query language that lets clients request exactly the data they need. More flexible than REST but requires a different server implementation and caching strategy.
  • gRPC – A high-performance RPC framework using Protocol Buffers. Good for internal microservices but less human-readable than REST.
  • Webhooks – Not a replacement for REST but a way for servers to push events to clients. REST is for request-response; webhooks are for event-driven.

Security and Performance Considerations

Security is a critical part of API design. Essential practices include:

  • Use HTTPS – Encrypt all traffic to prevent eavesdropping.
  • Authenticate and authorize – Use standard mechanisms like OAuth 2.0, JWT, or API keys. Never rely on the client to hide data.
  • Validate input – Check types, lengths, and formats. Never trust client data.
  • Rate limiting – Prevent abuse by limiting how many requests a client can make.
  • Cache appropriately – Use HTTP caching headers (e.g., Cache-Control, ETag) to reduce server load.

Performance-wise, keep responses small, use pagination, and consider compression (gzip). Avoid N+1 query problems by eager-loading related data when needed.

Frequently Asked Questions

What is the difference between PUT and PATCH?

PUT replaces the entire resource with the request body. PATCH applies a partial update, sending only the fields that need changing. Example: PUT /users/123 with {name: "Alice"} would remove other fields if the resource is a single object; PATCH /users/123 with {name: "Alice"} only updates the name.

Should I use singular or plural nouns in URIs?

Plural is the common convention: /users for the collection, /users/123 for an item. It is consistent and easy to understand. Some APIs use singular, but consistency matters more than which one you pick.

How do I handle nested resources?

Nested resources can be expressed as /users/123/orders to get orders for a specific user. However, deep nesting (more than two levels) becomes hard to maintain. Consider using query parameters or top-level resources with filters instead.

What is HATEOAS and do I need it?

HATEOAS (Hypermedia As The Engine Of Application State) means that responses include links to related actions. For example, an order response might include a link to cancel it. It makes the API self-documenting but adds complexity. Many APIs skip it and document links separately.

How should I version a REST API?

The simplest approach is to put the version in the URL: /v1/users. This is easy to implement and understand. Other options include custom headers or media types, but those are less common and harder to maintain.

What status code should I return for a validation error?

Use 400 Bad Request for validation errors that are the client’s fault. If the request is well-formed but the action is forbidden, use 403. If the resource does not exist, use 404. For server-side issues, use 500.

Related

Formula used
in t | Finish time | min | 50 | 0
in d | Distance | km | 10 | 0
out pace | Average pace | min/km | t / d | 2
out speed | Average speed | km/h | d / (t / 60) | 2

Each line is one input (in, sel, list) or one result (out: label, unit, formula, decimals). How the calculators work

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.