RESTful API

REST (Representational State Transfer) is a software architectural style for creating APIs and making them available on the web, following a set of principles that allow different applications to communicate efficiently and at scale.

REST APIs provide a simple, uniform interface for making data, content, algorithms, media, and other digital resources available through URLs.

A REST API is an API that follows REST's design principles. Its main characteristic is that it is based on the HTTP protocol, using HTTP methods (GET, POST, PUT, PATCH, DELETE) to perform operations, with resources identified by unique URLs.

What is the difference between REST and RESTful?

REST is an architectural style for web services based on rules for client-server communication. A RESTful service implements that style, using URLs and HTTP methods to identify and manipulate resources.

Understanding how to structure a REST API is essential to developing an application that really makes sense and is easy for the developers who will use your API to understand. REST APIs are also the most common APIs used on the web today.

Characteristics

The term REST originated with Roy Fielding in his dissertation, written in 2000. In it, he described a REST service with the following characteristics:

• Client-server: The server manages data while the client interacts with it. Their responsibilities should be clearly separated.

• Stateless: Each request from the client to the server must contain all the information. The server should not keep the client's state (session) on its side.

• Cacheable: Whenever possible, resources should be cached on the client or server side. Server responses must also include information about whether caching is allowed for the resource delivered. The goal is to improve performance on the client side while increasing scalability on the server side.

• Uniform interface: Use HTTP methods such as GET, POST, PATCH, PUT, and DELETE appropriately, with a clear structure for resources and their relationships.

A service is not RESTful merely because it sends JSON back and forth. Following the architectural constraints makes an API easier to use, more reliable, and more efficient.

Response to a request

An HTTP response always includes a status code and may also include data.

Status codes

Status codes accompany HTTP responses. They tell the client whether a request succeeded and, if it did not, help explain the likely cause.

Some examples are:

• 200 OK: The request succeeded.

• 201 Created: The request succeeded and a new resource was created.

• 400 Bad Request: The server could not understand the request.

• 404 Not Found: The server could not find the requested resource.

• 500 Internal Server Error: An unexpected server error occurred.

See the complete list of HTTP response status codes.

Data

The API designer decides which formats the API returns. JSON and XML are common choices.

Many newer REST APIs use JSON as their default or primary format. Some support both JSON and XML; in that case, the client can specify which format it wants in its request.

Implementation

Examples of using a RESTful API for basic CRUD (Create, Read, Update, Delete) operations:

Create a student

Use HTTP POST.

Request:

POST /aluno HTTP/1.1
Host: www.api.com.br
Content-Type: application/json

{
  "nome": "Saul Hudson",
  "cpf": "016.262.810-25",
  "nascimento": "1965-07-23"
}

Response (201 Created):

{
  "id": 3,
  "nome": "Saul Hudson",
  "cpf": "016.262.810-25",
  "nascimento": "1965-07-23"
}

List students

Use HTTP GET.

Request:

GET /aluno HTTP/1.1
Host: www.api.com.br

Response (200 OK):

[
  {
    "id": 1,
    "nome": "William Bruce Rose Jr.",
    "cpf": "151.668.780-94",
    "nascimento": "1962-02-06"
  },
  {
    "id": 2,
    "nome": "John Fogerty",
    "cpf": "241.090.550-16",
    "nascimento": "1945-05-28"
  },
  {
    "id": 3,
    "nome": "Saul Hudson",
    "cpf": "016.262.810-25",
    "nascimento": "1965-07-23"
  }
]

Retrieve a student

Use HTTP GET.

Request:

GET /aluno/1 HTTP/1.1
Host: www.api.com.br

Response (200 OK):

{
  "id": 1,
  "nome": "William Bruce Rose Jr.",
  "cpf": "151.668.780-94",
  "nascimento": "1962-02-06"
}

Update a student

Use HTTP PATCH.

Request:

PATCH /aluno/1 HTTP/1.1
Host: www.api.com.br
Content-Type: application/json

{
  "nome": "Axl Rose"
}

Response (200 OK):

{
  "id": 1,
  "nome": "Axl Rose",
  "cpf": "151.668.780-94",
  "nascimento": "1962-02-06"
}

Delete a student

Use HTTP DELETE.

Request:

DELETE /aluno/1 HTTP/1.1
Host: www.api.com.br

Response: 204 No Content (no response body).