REST API: What It Is and How It Works

REST API

REST API is the most widely used pattern for building web APIs. It uses standard HTTP methods and a clear resource-based URL structure that makes APIs intuitive, scalable, and easy to integrate with any client.

What Is a REST API

REST stands for Representational State Transfer. A REST API is an interface that allows clients such as browsers, mobile apps, and other servers to interact with a backend system using standard HTTP. Resources are identified by URLs, and actions are performed using HTTP methods like GET, POST, PUT, PATCH, and DELETE.

The term was introduced by Roy Fielding in his doctoral dissertation in 2000. Fielding was one of the principal authors of the HTTP specification, and REST was his attempt to describe the architectural style that made the web itself so scalable and interoperable. When people talk about REST APIs today, they are referring to APIs that follow this architectural style applied to web services.

REST is not a protocol or a standard with a formal specification. It is a set of design constraints. An API that follows those constraints is described as RESTful. In practice, many APIs described as REST APIs bend or break some of the constraints, but they still follow the general pattern closely enough to be recognisable and usable in the same way.

Core REST Principles

REST is built on a small set of constraints that, when followed together, produce APIs that are predictable, scalable, and easy to work with across different clients and platforms.

• Stateless: Each request must contain all the information the server needs to process it. The server does not store any client session state between requests. Authentication tokens, user identifiers, and any other context must be included in every request.
• Resource-based: Everything is a resource, and every resource is identified by a URL. A user is a resource at /users/42. A list of orders is a resource at /orders. The URL identifies what you are acting on, and the HTTP method identifies what action you are taking.
• Uniform Interface: Standard HTTP methods define the actions. GET retrieves data, POST creates a new resource, PUT replaces an existing resource, PATCH applies a partial update, and DELETE removes a resource. This consistency means developers can predict how an endpoint behaves before reading its documentation.
• Client-Server Separation: The client and server are independent. The client does not need to know how the server stores data. The server does not need to know what kind of client is making the request. Each can evolve independently as long as the API contract remains consistent.
• Cacheable: Responses should indicate whether they can be cached. When responses are cacheable, clients and intermediaries like reverse proxies can store them and serve them without hitting the server again, improving performance and reducing load.
• Layered System: A client does not need to know whether it is connected directly to the server or to an intermediary such as a load balancer, cache, or API gateway. Each layer only knows about the layer it communicates with directly.

REST API URL Design

Good URL design is one of the most visible aspects of a REST API. URLs should represent resources using nouns, not verbs. The HTTP method already describes the action, so the URL only needs to identify what resource is being acted on. A URL like /api/getUser is not RESTful. A URL like /api/users/42 is.

Collections use plural nouns. Individual resources use the collection path followed by an identifier. Nested resources reflect relationships between resources. For example, the orders belonging to user 42 would sit at /api/users/42/orders.

Example REST API Request and Response

The following example shows a basic GET request to retrieve a single user by ID. The client sends an HTTP request with an Authorization header containing a bearer token. The server responds with a JSON object representing the resource.

GET /api/users/42 HTTP/1.1
Host: api.techyall.com
Authorization: Bearer abc123token

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "name": "Alice Smith",
  "email": "alice@example.com"
}

The status code in the response tells the client what happened. A 200 means the request succeeded and the resource was returned. A 201 would indicate a new resource was created. A 404 would mean the resource was not found. Using the correct status codes consistently is just as important as correct URL design because clients rely on them to decide how to handle the response.

PUT vs PATCH

A common point of confusion is when to use PUT versus PATCH. PUT is intended for full replacement. When you send a PUT request, you are expected to include the complete representation of the resource. If you omit a field, that field may be cleared or reset on the server. PATCH is intended for partial updates. You send only the fields you want to change, and the server applies them without affecting the rest of the resource.

In practice, many APIs use PUT loosely and treat it the same as PATCH, only updating the fields that were sent. Checking the documentation for the specific API you are working with is always the safest approach, since implementations vary.

REST vs Other API Styles

REST is not the only way to design an API. GraphQL and SOAP are two other styles you will encounter, each with different trade-offs. Understanding where REST excels and where other approaches might be a better fit helps you make informed decisions when designing or choosing an API.

REST works well when your resources are clearly defined and your clients need straightforward access to them. GraphQL is often a better fit when different clients need different subsets of the same data, such as a mobile app that needs minimal fields and a desktop app that needs everything. SOAP remains in use in industries like banking and healthcare where strict contracts, formal schemas, and built-in error handling are requirements rather than preferences.

Versioning a REST API

As your API evolves, you will eventually need to make changes that are not backward compatible. Versioning allows you to introduce breaking changes without disrupting clients that depend on the existing behaviour. The most common approach is to include the version in the URL path, such as /api/v1/users and /api/v2/users. This makes the version explicit and easy to see in logs and documentation.

An alternative approach is to use a custom request header or the Accept header to specify the version, keeping the URL clean. Both approaches work. The URL-based approach is more visible and easier to test in a browser or with tools like Postman. The header-based approach is considered more technically correct from a REST perspective but requires more effort from API consumers to implement correctly.

Frequently Asked Questions

1. Does REST require JSON?
   No. REST can use any data format including XML, plain text, or even binary. JSON has become the de facto standard for REST APIs because it is lightweight, easy to read, and natively supported by every major programming language and browser. When someone says REST API without specifying a format, JSON is almost always what they mean.
2. What makes an API truly RESTful?
   A RESTful API follows the core REST constraints: it is stateless, uses resource-based URLs with standard HTTP methods, has a uniform interface, and separates client from server concerns. Many APIs call themselves REST APIs while bending some of these rules. For most practical purposes, using resource-based URLs and correct HTTP methods puts you in the right direction even if the implementation is not perfectly pure.
3. What is an API endpoint?
   An endpoint is a specific URL that represents a resource or a collection of resources. For example, /api/users is the endpoint for the users collection, and /api/users/42 is the endpoint for the individual user with ID 42. Each endpoint supports one or more HTTP methods, and the combination of method and URL defines a specific operation.
4. What is the difference between REST and HTTP?
   HTTP is the protocol that REST uses for communication. REST is an architectural style that defines how to design your API using HTTP. All REST APIs use HTTP, but not all HTTP-based APIs are RESTful. An API that uses HTTP but puts the action in the URL (like /api/deleteUser?id=42) is using HTTP without following REST conventions.
5. Should I use PUT or PATCH for updates?
   Use PATCH when you want to update only specific fields of a resource without affecting the rest. Use PUT when you want to replace the entire resource with a new representation. If you are building a simple form that edits a few fields, PATCH is the more appropriate choice. If you are replacing a configuration object entirely, PUT fits better. Many APIs implement PATCH for everyday updates and reserve PUT for full resource replacement.

Conclusion

REST APIs are the backbone of modern web and mobile applications. Their resource-based URL design, reliance on standard HTTP methods, and use of JSON make them predictable and easy to work with for developers across any language or platform. Understanding how to structure URLs correctly, choose the right HTTP method, and interpret status codes accurately is foundational knowledge for both frontend and backend development. To go deeper, explore HTTP methods, HTTP status codes, and JWT authentication.