API RESTful

O REST (REpresentational State Transfer) é um padrão de arquitetura de software para criar APIs e disponibilizá-las na Web, seguindo um conjunto de princípios para permitir a comunicação entre diferentes aplicativos de forma eficiente e escalável.

Fornecem uma interface simples e uniforme, podendo ser usadas para disponibilizar dados, conteúdo, algoritmos, mídia e outros recursos digitais por meio de URLs.

Uma API REST é uma API que está em conformidade com os princípios de design do REST. A principal característica de uma API REST é que ela é baseada no protocolo HTTP, utilizando os verbos HTTP (GET, POST, PUT, PATCH, DELETE) para realizar as operações e os recursos são identificados por URLs únicas.

Qual a diferença entre REST e RESTful?

Como mencionado anteriormente, o REST é padrão de arquitetura para desenvolver serviços WEB com base em um conjunto de regras para a comunicação entre cliente e servidor. E o RESTful basicamente é o serviço que realiza a implementação do padrão REST, utilizando URLs e métodos HTTP para identificar e manipular recursos.

Entender os conceitos de como estruturar uma API REST é fundamental para desenvolver uma aplicação que realmente faça sentido e que seja de fácil compreensão para os desenvolvedores que utilizarão sua API. Além disso, as APIs REST são as APIs mais comuns usadas na Web hoje.

Características

O termo REST surgiu com o Roy Fielding em sua dissertação que escreveu no ano de 2000. Nesta dissertação ele classificava um serviço REST com algumas características, apresentadas a seguir:

➤ Cliente-servidor: De um lado temos o servidor trabalhando com os dados e do outro o cliente fazendo suas interações. Esta separação de responsabilidades deve ser a mais clara possível.

➤ Sem estado (stateless): As requisições do cliente para o servidor deve conter todas as informações. O servidor não deve manter o estado do cliente (sessão) do seu lado.

➤ Cacheável: Quando possível, os recursos devem ser armazenados em cache no lado do cliente ou servidor. As respostas do servidor também precisam conter informações sobre se o armazenamento em cache é permitido para o recurso entregue. O objetivo é melhorar o desempenho do lado do cliente, enquanto aumenta a escalabilidade do lado do servidor.

➤ Interface uniforme: Uso correto dos verbos HTTP GET, POST, PATCH, PUT, DELETE, entre outros e de uma separação clara dos recursos e de seus níveis.

Um serviço REST não é aquele que simplesmente manda um JSON de um lado para o outro. Existem certas regras definidas para que possa ser mais fácil de ser usada, mais confiável e com melhor performance.

Retorno de uma requisição

Uma requisição sempre retorna um Status Code e pode retornar também dados.

Status Codes

São códigos que são enviados juntamente com a resposta de uma requisição HTTP. Esses códigos ajudam o cliente saber se a requisição foi bem sucedida. E se não foi, ajuda-o a entender qual foi a causa provável do erro.

Alguns exemplos de Status Code são:

➤ 200 OK: A requisição ocorreu com sucesso.

➤ 201 Created: A requisição ocorreu com sucesso e um novo recurso foi criado.

➤ 400 Bad Request: O servidor não entendeu a requisição.

➤ 404 Not Found: O servidor não encontrou o recurso solicitado.

➤ 500 Internal Server Error: Ocorreu uma falha inesperada no servidor.

A lista completa pode ser visualiza em Códigos de status de respostas HTTP.

Dados

O criador do API REST é quem decide em que formatos ele exibirá os dados como resposta. Entretanto, os formatos mais comuns são JSON e XML.

A maioria dos API REST mais recentes, têm JSON como formato padrão ou principal. Em muitos casos, fornecem ambos os formatos JSON e XML. Nesse caso, ao fazer a requisição, o cliente pode informar qual o formato que ele deseja receber os dados.

Implementação

Exemplos da utilização de uma API RESTful para operações básicas de CRUD (Create, Read, Update, Delete):

Cadastrar um aluno

Utilização do método HTTP POST.

Request:

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

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

Retorno:

// HTTP Code: 201 Created

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

Consultar os alunos

Utilização do método HTTP GET.

Request:

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

Retorno:

// HTTP Code: 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"
  }
]

Consultar um aluno

Utilização do método HTTP GET.

Request:

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

Retorno:

// HTTP Code: 200 OK

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

Alterar um aluno

Utilização do método HTTP PATCH.

Request:

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

{
  "nome": "Axl Rose"
}

Retorno:

// HTTP Code: 200 OK

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

Remover um aluno

Utilização do método HTTP DELETE.

Request:

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

Retorno:

// HTTP Code: 200 OK