What is REST API (RESTful API)? Explained

What is REST?

REST (Representational State Transfer) is a well-known architectural style used for providing standards between computer systems on the web, making it easier for systems to communicate with each other. Its main goal is to simplify interactions between clients and servers by providing a consistent, resource-based approach to accessing and manipulating data.

REST-compliant systems, often called RESTful systems, are defined by two key principles: client-server architecture and statelessness.

Let’s take a deep dive into each of these principles one-by-one.

Client-server architecture

In the REST architectural style, the implementation of the client and the server can be done independently without each knowing about the other. This means that the code on the client side can be changed at any time without affecting the operation of the server, and the code on the server side can be changed without affecting the operation of the client.

As long as each side knows what format of messages to send to the other, they can be kept modular and separate. Separating the user interface concerns from the data storage concerns, we improve the flexibility of the interface across platforms and improve scalability by simplifying the server components. Additionally, the separation provides each component with the ability to evolve independently.

By using a REST interface, different clients hit the same REST endpoints, perform the same actions, and receive the same responses.

Statelessness

Systems that follow the REST paradigm are stateless, meaning that the server does not need to know anything about what state the client is in and vice versa. In this way, both the server and the client can understand any message received, even without seeing previous messages. This constraint of statelessness is enforced through the use of resources, rather than commands. Resources are the nouns of the Web - they describe any object, document, or thing that you may need to store or send to other services.

These constraints help RESTful applications achieve reliability, performance, and scalability by ensuring that components can be managed, updated, and reused without disrupting the overall system, even during operation.

Next, let’s discuss what a REST API is and how it works.

What is a REST API?

A REST API (Application Programming Interface), also known as a RESTful API, is a way for applications to interact with each other over the web following REST principles. It provides a structured method for accessing and manipulating resources—such as users, products, or documents—using standardized HTTP methods (GET, POST, PUT, and DELETE).

In a REST API, each resource is identified by a unique URI (Uniform Resource Identifier), and data is typically exchanged in lightweight formats such as JSON or XML. The API acts as a contract between the client and the server, ensuring that requests are well-formed and responses are predictable. This consistency allows developers to integrate systems more easily, scale applications, and maintain a clear separation between frontend clients and backend services.

Here is a visual representation of how the REST API works:

Now, we’ll explore how client-server communication takes place when we are implementing a RESTful interface.

Client-server communication in REST

In the REST architecture, clients send requests to retrieve or modify resources, and servers send responses to these requests. Let’s take a look at the standard ways to make requests and send responses.

Making requests

REST requires that a client make a request to the server in order to retrieve or modify data on the server. A request generally consists of:

• An HTTP verb, which defines what kind of operation to perform
• A header, which allows the client to pass along information about the request
• A path to a resource
• An optional message body containing data

HTTP verbs

There are four basic HTTP verbs we use in requests to interact with resources in a REST system:

• GET: Retrieves a specific resource (by ID) or a collection of resources
• POST: Creates a new resource
• PUT: Updates a specific resource (by ID)
• DELETE: Removes a specific resource (by ID)

Headers and Accept parameters

In the header of the request, the client sends the type of content that it is able to receive from the server. This is called the Accept field, and it ensures that the server does not send data that cannot be understood or processed by the client. The options for types of content are MIME Types (or Multipurpose Internet Mail Extensions). They are used to specify the content types in the Accept field, including a type and a subtype. They are separated by a slash (/).

For example, a text file containing HTML would be specified with the type text/html. If this text file contained CSS instead, it would be specified as text/css. A generic text file would be denoted as text/plain. This default value, text/plain, is not a catch-all, however. If a client is expecting text/css and receives text/plain, it will not be able to recognize the content.

Other types and commonly used subtypes:

• image: image/png, image/jpeg, image/gif
• audio: audio/wav, audio/mpeg
• video: video/mp4, video/ogg
• application: application/json, application/pdf, application/xml, application/octet-stream

For example, a client accessing a resource with an id of 23 in an articles resource on a server might send a GET request like this:

GET /articles/23 
Accept: text/html, application/xhtml 

The Accept header field, in this case says that the client will accept the content in text/html or application/xhtml.

Paths

Requests must contain a path to a resource that the operation should be performed on. In RESTful APIs, paths should be designed to help the client know what is going on.

Conventionally, the first part of the path should be the plural form of the resource. This keeps nested paths simple to read and easy to understand.

A path like fashionboutique.com/customers/223/orders/12 is clear in what it points to, even if you’ve never seen this specific path before, because it is hierarchical and descriptive. We can see that we are accessing the order with an id of 12 for the customer with an id of 223.

Paths should contain the information necessary to locate a resource with the degree of specificity needed. When referring to a list or collection of resources, it is not always necessary to add an id. For example, a POST request to the fashionboutique.com/customers path would not need an extra identifier, as the server will generate an id for the new object.

If we are trying to access a single resource, we would need to append an id to the path.

For example:

• GET fashionboutique.com/customers/:id: Retrieves the item in the customers resource with the id specified.
• DELETE fashionboutique.com/customers/:id: Deletes the item in the customers resource with the id specified.

Sending responses

When a client makes a request to a RESTful API, the server must send back a response that clearly communicates both the outcome of the request and the format of any data returned. Responses typically include headers, which provide metadata such as content type and status codes, and may also include a body, which contains the requested resource data. Understanding how servers send responses is crucial for building reliable client-server interactions.

Content types

In cases where the server is sending a data payload to the client, the server must include a content-type in the header of the response. This content-type header field alerts the client to the type of data it is sending in the response body. These content types are MIME Types, just as they are in the accept field of the request header. The content-type that the server sends back in the response should be one of the options that the client specified in the accept field of the request.

For example, when a client is accessing a resource with id 23 in an articles resource with this GET Request:

GET /articles/23 HTTP/1.1 
Accept: text/html, application/xhtml 

The server might send back the content with the response header:

HTTP/1.1 200 (OK) 
Content-Type: text/html 

This would signify that the content requested is being returned in the response body with a content-type of text/html, which the client said it would be able to accept.

Response codes

Responses from the server contain status codes to alert the client to information about the success of the operation. As a developer, you do not need to know every status code, but you should know the most common ones and how they are used:

For each HTTP verb, there are expected status codes a server should return upon success:

• GET: Return 200 (OK)
• POST: Return 201 (CREATED)
• PUT: Return 200 (OK)
• DELETE: Return 204 (NO CONTENT)

If the operation fails, return the most specific status code possible corresponding to the problem that was encountered.

Examples of requests and responses

Let’s say we have an application that allows you to view, create, edit, and delete customers and orders for a small clothing store hosted at fashionboutique.com. We could create an HTTP API that allows a client to perform these functions:

If we wanted to view all customers, the request would look like this:

GET http://fashionboutique.com/customers 
Accept: application/json 

A possible response header would look like:

Status Code: 200 (OK) 
Content-type: application/json 

Followed by the customers data requested in application/json format.

Create a new customer by posting the data:

POST http://fashionboutique.com/customers 
Body: 
{ 
  “customer”: { 
    “name” = “Scylla Buss”, 
    “email” = “[email protected]” 
  } 
} 

The server then generates an id for that object and returns it back to the client, with a header like:

201 (CREATED) 
Content-type: application/json 

To view a single customer, we GET it by specifying that customer’s ID:

GET http://fashionboutique.com/customers/123 
Accept: application/json 

A possible response header would look like:

Status Code: 200 (OK) 
Content-type: application/json 

Followed by the data for the customer resource with id 23 in application/json format.

We can update that customer by inserting the new data using PUT:

PUT http://fashionboutique.com/customers/123 
Body: 
{ 
  “customer”: { 
    “name” = “Scylla Buss”, 
    “email” = “[email protected]” 
  } 
} 

A possible response header would have Status Code: 200 (OK), to notify the client that the item with an id of 123 has been modified.

We can also DELETE that customer by specifying its id:

DELETE http://fashionboutique.com/customers/123 

The response would have a header containing Status Code: 204 (NO CONTENT), notifying the client that the item with an id of 123 has been deleted, and nothing in the body.

With client-server communication covered, let’s learn how to design a REST system.

Designing a REST system

Let’s imagine we are building a photo collection site. We want to make an API to keep track of users, venues, and photos of those venues. This site has an index.html and a style.css. Each user has a username and a password. Each photo has a venue and an owner (i.e. the user who took the picture). Each venue has a name and street address.

We need to design a REST system that would accommodate:

• Storing users, photos, and venues
• Accessing venues and accessing certain photos of a certain venue

Start by writing out:

• What kinds of requests we would want to make
• What responses the server should return
• What the content-type of each response should be

Possible solution: Models

User model representing application users:

{ 
  “user”: { 
    "id": <Integer>, 
    “username”: <String>, 
    “password”:  <String> 
  } 
} 

Photo model representing uploaded venue photos:

{ 
  “photo”: { 
    "id": <Integer>, 
    “venue_id”: <Integer>, 
    “author_id”: <Integer> 
  } 
} 

Venue model representing venues in the system:

{ 
  “venue”: { 
    "id": <Integer>, 
    “name”: <String>, 
    “address”: <String> 
  } 
} 

Possible solution: Requests/Responses

GET requests

Requesting the homepage (index.html):

GET /index.html 
Accept: text/html 

Response:

200 (OK) 
Content-type: text/html 

Requesting the stylesheet (style.css):

GET /style.css 
Accept: text/css 

Response:

200 (OK) 
Content-type: text/css 

Fetching all venues:

GET /venues 
Accept: application/json 

Response:

200 (OK) 
Content-type: application/json 

Fetching a single venue by ID:

GET /venues/:id 
Accept: application/json 

Response:

200 (OK) 
Content-type: application/json 

Fetching a specific photo of a venue:

GET /venues/:id/photos/:id 
Accept: application/json 

Response:

200 (OK) 
Content-type: image/png 

POST requests

Creating a new user:

POST /users 

Response:

201 (CREATED) 
Content-type: application/json 

Creating a new venue:

POST /venues 

Response:

201 (CREATED) 
Content-type: application/json 

Uploading a new photo for a venue:

POST /venues/:id/photos 

Response:

201 (CREATED) 
Content-type: application/json 

PUT requests

Updating a user by ID:

PUT /users/:id 

Response:

200 (OK) 

Updating a venue by ID:

PUT /venues/:id 

Response:

200 (OK) 

Updating a photo of a venue:

PUT /venues/:id/photos/:id 

Response:

200 (OK) 

DELETE requests

Deleting a venue by ID:

DELETE /venues/:id 

Response:

204 (NO CONTENT) 

Deleting a specific photo of a venue:

DELETE /venues/:id/photos/:id 

Response:

204 (NO CONTENT) 

Finally, let’s discuss the advantages and disadvantages of REST.

Advantages and disadvantages of REST

REST offers several advantages, including:

• Simplicity: Relies on widely understood HTTP methods and status codes.
• Scalability: Statelessness allows easy horizontal scaling.
• Flexibility: Supports multiple data formats (JSON, XML, etc.).
• Inter-operability: Standardized approach across diverse systems.

However, there are some disadvantages as well:

• Over-fetching/Under-fetching: Clients may receive too much or too little data.
• Performance limitations: Multiple requests may be required to retrieve related resources.
• Lack of strict standards: Different implementations may vary, causing inconsistencies.
• Not always efficient for complex interactions: Alternatives like GraphQL may be better in some cases.

Conclusion

In this tutorial, we explored what REST is, how clients and servers communicate in it, and how a REST system can be designed for real-world applications such as users, venues, and photos. We also discussed REST APIs and looked at the advantages and disadvantages of REST to get an idea of how to use it effectively.

REST has become a cornerstone of web services, enabling simple, scalable, and flexible communication between clients and servers. While REST is not without drawbacks, its widespread adoption and ease of use make it an essential concept for any developer working with distributed systems. As technology evolves, REST continues to be a reliable and adaptable choice for building robust web services.

If you are interested in learning how to create REST APIs, check out the Create REST APIs with Spring and Java course on Codecademy.

Frequently asked questions

1. What do you mean by REST API?

A REST API is a special kind of interface that enables clients and servers to communicate using a set of REST principles based on HTTP methods, statelessness, and resource representation. It exposes resources through endpoints, usually returning data in formats like JSON or XML.

2. What’s the difference between API and REST API?

An API is a general term that refers to any interface that allows software applications to communicate with each other. A REST API is a particular type of API that follows REST principles—using HTTP methods, stateless communication, and resource-based endpoints. In short, all REST APIs are APIs, but not all APIs are REST APIs.

3. Is REST API just HTTP?

No. REST is an architectural style, not a protocol. While most REST APIs use HTTP as the transport protocol, REST principles can be applied over other protocols too. However, HTTP has become the most common choice due to its simplicity and wide adoption.

4. Do all REST APIs use JSON?

No. JSON is the most popular format because it is lightweight, easy to read, and well-supported by modern programming languages. However, REST APIs can return other formats such as XML, YAML, or even plain text, depending on the client’s Accept header and the server’s implementation.

5. Do REST APIs use XML?

Yes, REST APIs can use XML. In fact, before JSON became dominant, XML was widely used as the standard data format for REST APIs. While JSON is now more common, some APIs still support XML, particularly in enterprise or legacy systems.