Banner Post

Criando APIs REST

A explicação que vou dar neste tutorial de boas práticas é um resumo deste vídeo (em inglês). Como sou desenvolvedor Java a mais de uma década, o vídeo é do pessoal da SpringDeveloper, utilizando exemplos em Java, mas mesmo para outras linguagens o vídeo é muito bom.



Se quiser uma explicação mais detalhada sobre REST ou requisições HTTP, o vídeo é uma referência mais adequada, este tutorial tem um intuito mais prático.

O primeiro ponto a discutir são os HTTP Request Methods que vamos utilizar, apesar de existir uma série deles, vou focar apenas nos mais utilizados.


GETEste método é o mais simples de todos e permite de foma rápida enviar na própria URL (e testar pelo browser) o que queremos buscar. Deve ser utilizado para buscas, onde o serviço retornará um valor, objeto ou lista.
POSTMétodo adequado para criação de novos registros ou funcionalidades adversas, como efetuar um cálculo complexo.
PUTAtualização de registros.
DELETERemoção de registros.

Ainda existe mais um utilizado, mas em bem menor escala, o OPTIONS. Este método retorna quais as opções que o servidor aceita (como headers aceitos e formas de comunicação). Toda chamada AJAX feita para domínios diferentes do da página carregada, os browsers fazer uma pré-chamada (preflight request) para ver se o destino possibilita CORS.


Padrões de URL

Supondo que vamos implementar um sistema CRUD para um cadastro de pessoas, vamos imaginar as seguintes funcionalidades que iremos expor através de serviços REST:

  • Listar pessoas
  • Criar uma pessoa
  • Buscar uma pessoa
  • Alterar pessoa
  • Remover pessoa

Para isso, utilizamos um mesmo contexto de página para todos os serviços de pessoa. Portanto iniciamos com o caminho:


/pessoas


Nesta URL temos nosso primeiro serviço: Listar Pessoas. Ao chamar este serviço via método GET, o sistema deverá retornar uma lista de pessoas, por exemplo:

[
  {
    "id":1,
    "nome":"Guilherme",
    "sobrenome":"Gomes"
  },{
    "id":2,
    "nome":"Frodo",
    "sobrenome":"Bolseiro"
  }
]


Para o segundo serviço - Criar uma pessoa - podemos utilizar a mesma URL, mas dessa vez através do método POST. Assim, a aplicação cliente  (front-end) poderia enviar um JSON/XML como este:


{"nome":"Son","sobrenome":"Goku"}


O terceiro serviço - Buscar uma pessoa - pode ser feito através de método GET através de outra URL.

/pessoas/3

Neste caso, o serviço retornaria a última pessoa que insermos.

{"nome":"Son","sobrenome":"Goku"}

E alterando o parâmetro de 3 para 2 ou 1, podemos buscar as outras duas pessoas retornadas na lista anterior (que agora teria um elemento a mais).


A alteração de pessoa seria feita na mesma URL que antes (exemplo: /pessoas/3), através do método PUT. Utilizando o mesmo modelo de JSON, podemos alterar os valores de um registro. Por exemplo, se chamarmos a URL /pessoas/2, via método PUT com o JSON:

{"nome":"Bill","sobrenome":"Cosby"}

Estamos alterando o Frodo Bolseiro para Bill Cosby.


Por último, podemos remover uma pessoa apenas chamando a mesma URL de antes, mas com o método DELETE. Por exemplo, chamando /pessoas/1 via método DELETE, removemos o Guilherme Gomes da nossa lista.


Como eu falei anteriormente, podemos utilizar o método POST para funcionalidades distintas também, um exemplo seria criar um serviço na URL /mapa/rota em que enviamos duas informações: ponto origem e ponto destino; e o serviço retorna a melhor rota entre os dois pontos, com uma lista de endereços, ou pontos.


HTTP Status

É muito importante também utilizar os códigos de Status HTTP  nos retornos dos serviços apropriadamente, com os 2XX com os códigos de sucesso, 3XX para redirecionamento, 4XX para erros de cliente e 5XX para erros de servidor.

Alguns exemplos:

  • Se o nosso serviços /pessoas via método GET for retornar uma lista vazia, pois não encontrou pessoas na base de dados, poderia retornar a lista vazia [] com o HTTP Status 204 (No content - Sem conteúdo).
  • Se algum erro inesperado ocorre na aplicação (como falha de comunicação com o banco de dados), retornar o status 500 (Internal Server Error - Erro Interno do Servidor);
  • Se o cliente não tem permissão de acesso, retornar 403 (Forbidden - Acesso proibído).
  • Caso os dados enviados pelo cliente são insuficientes ou estão preenchidos de forma errada, retornar 400 (Bad Request - Requisição mal-feita).

Um erro muito comum é esquecer de colocar os HEADERS Accept e Content-type com os dados corretos de "application/json", "application/xml", etc... e acabar com um status 415 (Unsupported Media Type - Tipo de mídia não suportado).

  • Accept - qual os formatos que o cliente aceita que sejam enviados pelo servidor;
  • Content-type - formato do conteúdo sendo enviado pelo servidor.

Nos exemplos, ambos os HEADERS sempre seriam preenchidos com "application/json", pois sempre foi produzido e consumido JSON.


Espero que tenha ajudado!

Gostou? Quer fazer comentários? Falar comigo? Entra em contato :D