What is REST? RESTful APIs explained

Although nowadays REST APIs are well-known and widely used in the software industry. In their early days around the 2000s, their emergence marked a substantial change in how web services communicate. Until then, the common practice was to use SOAP, a protocol to exchange information using XML. Despite still being used today, REST is now practically the default choice when thinking about developing a new API.

What is a REST API?

REST is an architecture used for developing web APIs, where two parts - the client and the server - communicate with each other to exchange information.

The set of REST rules was initially described by Roy Fielding in his doctoral dissertation. Over the years, it has become more popular due to its ease of use, scalability, and flexibility.

An API can be considered RESTful if it adheres to the following concepts:

1. Uniform Interface. Requests and responses should follow a standard format. In the case of REST APIs over HTTP, methods and URIs are used to identify each resource, and information is sent using the structure of HTTP messages.
2. Decoupling. The client and server act independently. All interactions start when the client initiates a request and waits for the server to respond.
3. Statelessness. Requests to the server from the client must contain all the necessary information to process that request. This statement means that, for example, the server should not store information about the client’s session. Instead, the client should send this information to the server in each request (e.g., through headers).
4. Layered Architecture. The REST architecture allows a layered system where each layer can only interact with the immediately following layer.
5. Cache. Whenever possible, the information sent or received should be cached. For this, the server has to specify, through headers, whether the response can be cached and for how long.

And you might wonder what a resource is. It is a data entity that can be accessed and manipulated through a REST API. For example, in a simple API that allows managing users, user would be a resource.

How does a REST API work?

The interaction cycle of a REST API is always initiated by a client and can be summarized as follows:

• The client sends an HTTP request to the server. The request includes the URI of the resource and, in some cases, additional data in the request body.
• The server processes the request according to the HTTP method and the provided URI. It performs the necessary operations on the resource and may return data as a response.
• The server responds with an HTTP status code indicating the execution result. It may also include relevant data in the response body, such as the representation of the requested resource.

What elements does a REST API call contain?

As mentioned earlier, communication with REST APIs is done through HTTP requests. The anatomy of an HTTP request consists of several elements. Each serves a purpose, and together, they inform the server about the action to be executed.

• URI. Also called API endpoint, it specifies the path of the resource you want to act on. For example /users.

• Method. Determines the type of action to be executed on the server. The most common ones are:

  • GET is used to request information.
  • POST is used to send data and/or create new resources.
  • PUT and PATCH are used to update data.
  • DELETE is used to delete resources.

  To illustrate these concepts, if you were developing an API to manage users, you could create the following endpoints:

  HTTP Method	Path	Used for
  GET	/users	List all users
  POST	/users	Create a new user
  GET	/users/1	Fetch user 1 information
  PUT	/users/1	Update all attributes of user 1
  PATCH	/users/1	Update some attributes of user 1
  DELETE	/users/1	Delete user 1

• Headers. Can contain information such as an authentication token, cookies, or the expected response format.

• Body. Additional data associated with the resource. For example, if you were creating a user, it would include information such as name, email, date of birth, etc.

What elements does a REST API response contain?

• Status Code. A three-digit code indicating the result of the request. These codes fall into five types, depending on whether the server successfully executed the API endpoint or not. These are the ranges:

  • 100-199: indicate that the request was received and is being processed.
  • 200-299: indicate that the request was executed correctly.
  • 300-399: indicate that there has been a redirection.
  • 400-499: indicate an error on the client side.
  • 500-599: indicate an error on the server side.

• Headers. Metadata sent along with the response body. They add additional information such as the date, server description, response format type, and cache data, among others.

• Body. The bulk of the data that the server sends back to the client. For example, if you sent a request to create a user, the server would return information about the user object.

How can I create my REST API on Hello API?

From Hello Hello API, you can easily add your REST API and run it from the browser or share it with anyone through a URL to your playground.

To do this, the first step is to sign up.

Once registered, in the left sidebar, add as many endpoints as you want. For each of them, you can configure the HTTP method, URL, headers, parameters, and body.

How can I execute a REST API endpoint on Hello API?

To execute an endpoint, once you have configured all its parameters, click the “Run” button. This action will send a request to the server. On the right panel, you will see the results of the execution.

How can I share my REST API?

Hello API allows you to share your API with anyone. Anyone with your public URL can view and execute the endpoints you have defined. But don’t worry, they won’t be able to modify them.

To share your playground, click the “Playground page” option in the left sidebar menu. Your public URL will open in a new tab. Copy that URL and send it to anyone you want to showcase your fantastic API!