What Is a REST API?

REST as an Architectural Style for Web APIs

What is a REST API? A REST API is an application programming interface that follows the principles of REST, short for Representational State Transfer. REST is an architectural style, meaning a set of design constraints, rather than a protocol or a product.

Roy Fielding described the style in his doctoral dissertation in 2000. Fielding was also one of the authors of the HTTP specification, and REST reflects how the web itself works. Clients request representations of resources, and servers respond with the current state of those resources. A representation is one format of a resource, such as a JSON document that describes a customer. Most REST APIs run over HTTP and exchange data in formats such as JSON.

The Core Principles Behind REST

• Resources. Everything the API exposes is a resource with its own URL. A customer, an invoice or a domain each has an address.
• Client-server separation. The client handles the user interface and the server handles data and rules, so each side can change independently.
• Statelessness. Each request carries all the information the server needs, and the server keeps no session context between calls.
• Cacheability. Responses indicate whether they can be stored and reused, which reduces load on the server.
• Uniform interface. Resources are handled through standard methods and representations, so clients learn fewer special rules.

The full definition also includes a layered system, optional code on demand, and a principle called hypermedia, in which responses contain links to related actions. Many APIs described as RESTful skip hypermedia, which is common in practice.

What RESTful Design Looks Like in Practice

A RESTful API organizes its URLs around nouns and uses HTTP methods for actions. A list of customers lives at a collection address, each customer has its own address, and the method shows what the client wants to do with it. The URL design itself is covered in API endpoints.

A typical REST API therefore uses GET to read, POST to create, PUT or PATCH to update and DELETE to remove. Responses use standard status codes, and the body is usually JSON. Because each call is self-contained and uses standard HTTP features, tools such as browsers, proxies and content delivery networks can often work with the API as well.

REST is a style, not a certification that an API must pass. Two APIs can both be called REST and still differ in naming, error formats and versioning, which is why good documentation matters. REST is often compared with SOAP and GraphQL.