What is REST API?

A REST API, or representational state transfer application programming interface, is an architectural style that’s commonly seen as the standard for designing and building the networked applications that power the web. It provides a set of rules and constraints that, when followed, result in web services that are simple, scalable, and easy to integrate.

REST API defined

A REST API is an API that conforms to the design principles of the REST architectural style. At its core, REST revolves around the idea of resources, which can be any piece of information like a user, product, document, or collection of items. 

A REST API provides a way for a client application to access and manipulate these resources using a predefined set of stateless operations.

How does a REST API work?

1. Client sends request

A client application (like a mobile app, web browser, or another server) initiates a request to the API to perform an action. This request is sent to a specific URL and includes an HTTP method, headers with metadata, and sometimes a request body with data.

2. Server processes request

The server receives and validates the request, confirming that the client is authenticated and authorized to perform the requested action. It then processes the request, which could involve retrieving data from a database, creating a new resource, or updating an existing one.

3. Server sends response

After processing the request, the server sends a response back to the client. This response includes an HTTP status code indicating the outcome (for example, 200 OK for success, 404 Not Found if the resource doesn't exist, 401 Unauthorized for security issues), along with the requested data in the response body.

4. Data transfer

The data transferred between the client and server is a "representation" of the state of the resource. JSON (JavaScript Object Notation) is the most common format for this data because it is lightweight, human-readable, and easy for programming languages to parse.

REST API architecture and components

The power and scalability of REST come from a set of architectural constraints that guide its design. A system that adheres to these constraints is considered "RESTful."

REST API model diagram

Resources

A resource is a fundamental concept in REST. It is an object with a type, associated data, relationships to other resources, and a set of methods that operate on it. For example, in an e-commerce API, a "product" or a "customer" would be a resource.

URIs (uniform resource identifiers)

Each resource is uniquely identified by a URI. A well designed API uses clean, descriptive, and consistent URIs to identify its resources. For example, /users might identify a collection of users, and /users/123 would identify a specific user with the ID 123.

Representations

A client does not interact with the resource directly but with a representation of that resource. The most common representation format is JSON, but others like XML or HTML can also be used. This provides a flexible way to represent the state of a resource.

Statelessness

Every request from a client to the server must contain all the information the server needs to understand and process the request. The server does not store any client context or session state between requests. This constraint makes REST APIs highly scalable because any server can handle any request.

Client-server architecture

The client and server are separated, with the API acting as the interface between them. This separation of concerns allows the client-side application and the server-side application to evolve independently.

Uniform interface

REST requires a consistent, uniform interface between the client and server. This is achieved through the use of standard HTTP methods, URIs for resource identification, and hypermedia as the engine of application state (HATEOAS).

Cacheability

Responses from the server should be defined as cacheable or non-cacheable. When a response is cacheable, a client or intermediary can reuse that response for subsequent, identical requests, which can significantly improve performance and reduce server load.

Layered system

A client connected to a REST API cannot ordinarily tell whether it is connected directly to the end server or to an intermediary along the way. Intermediary servers, such as API gateways or load balancers, can be introduced to the architecture to improve scalability, security, and performance.

REST API best practices

URIs should represent resources, so they should use nouns (plural for collections, singular or an ID for a specific item), not verbs. For example, use /users to represent all users, not /getAllUsers.

Use the standard HTTP verbs to represent actions: GET for retrieval, POST for creation, PUT for updates, and DELETE for removal. This creates a predictable and consistent interface.

A key principle of REST is that a response should include links to other related actions or resources. This allows the client to navigate the API dynamically without having to hard-code URI patterns.

When you need to make breaking changes to an API, introduce a new version. The most common practice is to include the version number in the URI, such as /api/v2/users. This allows existing clients to continue using the old version while new clients can adopt the new one.

When a request fails, provide a clear, useful error message in the response body along with the appropriate HTTP status code (for example, 400 Bad Request, 500 Internal Server Error). This helps the client-side developer understand what went wrong.

Protect your API by implementing robust authentication (for example, OAuth 2.0, API keys) to verify the client's identity and authorization to ensure the client only has access to the resources they are permitted to see. Always use TLS/SSL to encrypt traffic.

For endpoints that can return a large number of items, implement pagination to return data in manageable chunks. Also, provide query parameters to allow clients to filter and sort the results, which reduces the amount of data transferred.

Benefits of using REST APIs

Simplicity and readability

REST APIs use standard HTTP methods and human-readable URIs, making them relatively easy for developers to learn, use, and debug. The self-descriptive nature of the interface simplifies integration efforts.

Scalability

The stateless nature of REST is a key enabler of scalability. Since the server doesn't need to maintain client sessions, it's easy to distribute requests across multiple servers, and new servers can be added to handle increased load without complexity.

Flexibility

REST supports a variety of data formats, with JSON being the most popular due to its lightweight nature and broad support. This flexibility allows REST APIs to be used by a wide range of client applications, from web browsers to mobile devices and IoT sensors.

Decoupling of client and server

The client-server architecture enforced by REST creates a clear separation of concerns. This allows developers to work on the client-side frontend and the server-side backend independently, which can accelerate development cycles.

Language agnostic

Because REST is an architectural style built on standard HTTP, it can be implemented in any programming language and consumed by any client capable of making HTTP requests. This provides maximum interoperability between diverse technology stacks.

REST API examples

Public API example

A common use case is a mobile weather app fetching the current weather for a specific location from a public weather API.

The client application makes an HTTP GET request to the API endpoint, including the location and an API key for authentication.

curl

"https://api.weather-service.com/v1/current?location=94043&key=YOUR_API_KEY"

curl

"https://api.weather-service.com/v1/current?location=94043&key=YOUR_API_KEY"

The server processes the request, retrieves the weather data for the specified location, and returns a JSON response.

{

 "temperature": 20,

 "unit": "celsius",

 "condition": "Clear",

 "humidity": 55

}

{

 "temperature": 20,

 "unit": "celsius",

 "condition": "Clear",

 "humidity": 55

}

Internal API example

In a microservices architecture, a "product" service might need to get an updated price from an "inventory" service before displaying it on an e-commerce site. 

The product service makes an internal HTTP GET request to the inventory service's API endpoint for a specific product ID.

curl

"http://inventory-service.internal/api/products/PN-5821/price"

curl

"http://inventory-service.internal/api/products/PN-5821/price"

The inventory service looks up the current price and returns a simple JSON response.

{

"productId": "PN-5821",

"price": 1299.99,

"currency": "USD"

}

```

{

"productId": "PN-5821",

"price": 1299.99,

"currency": "USD"

}

```

Solve your business challenges with Google Cloud

New customers get $300 in free credits to spend on Google Cloud.

Additional resources

Take the next step

Start building on Google Cloud with $300 in free credits and 20+ always free products.

Google Cloud