What is a REST API?

What is a REST API?

A REST API (Representational State Transfer Application Programming Interface) is an architectural style for building networked services that uses standard HTTP methods to create, read, update, and delete resources. Defined by Roy Fielding in his doctoral dissertation in 2000, REST has become the dominant pattern for web APIs because its constraints map naturally to how HTTP works, making REST services straightforward to design, consume, and scale.

REST treats every piece of data as a resource identified by a URL. A customer record, a payment transaction, a product listing: each has its own endpoint. Clients interact with those resources using HTTP verbs, and responses carry the resource state in a standard format, typically JSON.

The Six REST Constraints

REST is defined by six architectural constraints that distinguish it from earlier RPC-style approaches:

• Stateless: Each request carries all the information the server needs. The server holds no client session state between requests, making REST services horizontally scalable: any server in a pool can handle any request.
• Uniform interface: Resources are identified by URIs, manipulated through standard representations, and described using consistent HTTP methods. Any developer familiar with REST can interact with any REST API using the same mental model.
• Client-server separation: The client and server evolve independently. The client does not need to know how data is stored; the server does not need to know how the client renders it.
• Cacheable: Responses can be marked cacheable, allowing clients and intermediaries to serve subsequent identical requests from cache, reducing server load and latency.
• Layered system: Clients do not need to know whether they are communicating directly with the origin server or through a load balancer, CDN, or API gateway.
• Code on demand (optional): Servers may send executable code to clients. Rarely used in practice.

HTTP Methods and CRUD Operations

The mapping between HTTP methods and data operations is one of REST's defining features:

• GET /resources: retrieve a collection
• GET /resources/{id}: retrieve a single resource
• POST /resources: create a new resource
• PUT /resources/{id}: replace a resource entirely
• PATCH /resources/{id}: update specific fields of a resource
• DELETE /resources/{id}: remove a resource

Combined with consistent HTTP status codes (200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error), well-designed REST APIs are largely self-documenting for developers already familiar with the pattern.

REST API Design Best Practices

Several conventions have become de facto standards for REST API design beyond the core HTTP method mapping:

• Use nouns for resource names, not verbs. /orders rather than /getOrders or /createOrder.
• Use plural resource names. /customers/{id} rather than /customer/{id}.
• Version your API. Prefix endpoints with /v1/ or use a version header to allow backward-incompatible changes without breaking existing clients.
• Return appropriate status codes. 201 Created for new resources, not just 200. 422 Unprocessable Entity for validation failures, not just 400.
• Paginate collections. Return page size, offset, and total count in collection responses to avoid unbounded result sets.
• Document with OpenAPI. The OpenAPI Specification (formerly Swagger) is the standard format for machine-readable REST API documentation, enabling client SDK generation and interactive API explorers.

Teams building APIs as part of a software engineering engagement or a custom software development project typically establish these conventions in an API style guide early in the project to ensure consistency across endpoints and teams.