REST API Basics: Methods, Status Codes and Design

Mobile apps, web front ends, IoT devices and other services all talk to backends through APIs. REST (Representational State Transfer) is the most common style for web APIs because it builds directly on the way HTTP works. This article covers the basics a developer needs to use and design REST APIs well.

REST API constraints

Roy Fielding defined REST in his 2000 dissertation as a set of constraints:

1. Client-server: user interface and data storage are separated, so each can evolve independently.
2. Stateless: each request contains all the information the server needs; the server keeps no client session between requests.
3. Cacheable: responses say whether they can be cached, reducing load and latency.
4. Uniform interface: resources are identified by URIs and manipulated through representations using standard methods, with self-descriptive messages.
5. Layered system: clients cannot tell whether they talk to the origin server or to proxies, gateways or load balancers in between.
6. Code on demand (optional): servers may send executable code such as scripts.

Resources and URLs

Design URLs around nouns (resources), not verbs, and use plural collection names:

Use query parameters for filtering, sorting and paging: GET /orders?status=shipped&sort=-date&page=2.

Download diagram (WebP)

Representations: JSON

Most REST APIs exchange JSON. A request to create an order might send:

{
  "customerId": 57,
  "items": [{ "sku": "PT-100", "qty": 2 }],
  "shipTo": "Pune"
}

and the server replies with 201 Created, a Location header pointing to /orders/1001 and the created order in the body. Use consistent naming (camelCase or snake_case, not both), ISO 8601 dates and explicit units.

Status codes to use

Return a consistent error body, for example a code, a human readable message and the field that failed, so clients can handle errors predictably.

Design best practices

• Versioning: include a version in the path (/v1/orders) or a header, and avoid breaking changes within a version.
• Pagination: never return unbounded lists; use page and size or cursor based paging, and return links or a next cursor.
• Filtering and field selection: let clients ask only for what they need.
• Security: always use HTTPS; authenticate with tokens such as OAuth 2.0 bearer tokens; validate every input; apply rate limits; never trust client side checks alone.
• Documentation: describe endpoints with the OpenAPI specification so clients and tests can be generated.
• Statelessness: keep session state out of server memory so any instance can serve any request and the API scales horizontally behind a load balancer.
• Caching: use Cache-Control and ETag headers on read endpoints.

Testing and documenting a REST API

During development, tools such as curl, Postman or the browser’s developer console send requests and show the raw status, headers and body. An OpenAPI description lets teams generate interactive documentation, client libraries and contract tests from one source. Automated tests should check each endpoint for the success case, validation errors, missing authentication, missing resources and permission failures, comparing both the status code and the shape of the JSON. Monitoring in production then tracks error rates and response times per endpoint, so problems are found before users report them.

Rate limits, quotas and clear deprecation notices in responses help clients adapt when an API changes or is under heavy load. Publish a changelog so integrators know what changed and when.

REST and the backend

Behind the API, a backend application validates requests, applies business rules and reads or writes a database whose tables should be well designed; see database normalization. Clean code structure, such as the SOLID principles, keeps controllers, services and data access layers separate and testable. Every endpoint should be covered by integration tests that check status codes and response bodies.

Alternatives to REST include GraphQL, where clients specify exactly the fields they need in one query, and gRPC, which uses binary messages over HTTP/2 for fast service to service calls. REST remains the most common choice for public web APIs because it is simple, cache friendly and works with every HTTP tool.