As APIs seguem o padrão REST, que trabalham com recursos para definir
os formatos de url. Um recurso pode ser, por exemplo, a URL /api/v1/users,
que é responsável por listar e criar usuários. Seguindo esta lógica, a URL
/api/v1/users/1 identifica um elemento do recurso de usuários, que
representa o usuário de id 1. Esta URL do elemento permite buscar os dados do
usuário que ela identifica, além de permitir alterar e apagar este mesmo
usuário. O que define qual operação será realizada por estas URLs são
os métodos HTTP.
Os métodos HTTP são utilizados na API para descrever as operações que estão sendo realizadas, assim como o padrão REST preve. Segue abaixo uma descrição dos métodos e seus usos:
O método GET é utilizado para busca de informações das APIs, os dois
usos mais comuns para ele é o uso na listagem de itens de um recurso
e na busca individual de um recurso de uma API.
O método POST é utilizado para criação de um recurso nas APIs, como
por exemplo a criação de um novo usuário em uma API de gerenciamento
de usuários.
O método PUT é utilizado para atualizar recursos existentes nas APIs,
e pode ser utilizado para atualizar parcialmente os dados do recurso.
Por exemplo, pode ser feita uma requisição enviando somente um novo email
para um usuário existente, mantendo os outros dados deste usuário.
O método DELETE é utilizado para remoção de recursos de uma API.
As APIs que proveem este método normalmente retornarão um estado de
não encontrado se for realizado uma tentativa de apagar um recurso
que não existe.
Algums cabeçalhos HTTP são utilizados por padrão em todas as APIs, segue a listagem deles
Content-Type - Usado para descrever o formato dos dados retornados,
na maioria das APIs o valor será application/json.
Pode ser utilizado tanto para a requisição quanto para a resposta. Exemplo:
HTTP/1.1 200 OK
Content-Type: application/json
Host - Usado para descrever o hostname de destino da requisição. Devido
a possibilidade de um servidor prover mais de um hostname (estar rodando
mais de uma aplicação no mesmo IP), o valor deste item é utilizado para
identificar o serviço que está sendo acessado. A maioria das bibliotecas
de requisições HTTP e browsers inserem este cabeçalho automáticamente.
GET /api/v1/users HTTP/1.1
Host: api.empresa.com
Authorization - Este cabeçalho é utilizado para enviar o token de
autorização da API, para garantir que quem está acessado a API tem
permissão de executar a operação. É adicionado o prefixo Bearer
antes do token de autenticação, que se refere ao formato de autenticação
que está sendo utilizado.
GET /api/v1/users HTTP/1.1
Host: api.empresa.com
Authorization: Bearer asfasd123dfas.342afsdaf.324213asfdfas
As APIs adotam um subconjunto dos status HTTP existentes para identificar os status de retorno das requisições realizadas para as APIs. Segue os status e os seus significados:
Status 1XX são utilizados para prover informações sobre o recurso requisitado.
102 - Processing - O recurso requisitado ainda está sendo processado
e não está pronto para ser retornado
Status 2XX são status que identificam requisições bem sucedidas.
200 - OK - Requisição realizada com sucesso
202 - Accepted - A requisição foi aceita pelo servidor e será
processada em background
Status 4XX são status que identificam erros do lado do cliente, como por exemplo um erro no formado dos dados ou falta de informações na requisição
400 - Bad Request - Erro nos dados da requisição, deve ser verificado
o corpo da resposta para identificar que erro ocorreu
401 - Unauthorized - Token de acesso não foi enviado na requisiçao ou
o token expirou, deve ser requisitado um novo token antes de continuar
403 - Forbidden - O token não tem permissão de acesso a esta API ou
ao método sendo executado, ex: o token tem permissão somente de leitura
nesta API e foi realizado uma tentativa de atualização de um recurso
404 - Not Found - O recurso requisitado não foi encontrado ou
a API não existe
405 - Method Not Allowed - O recurso da API não suporta este método,
por exemplo, foi feita uma requisição DELETE na API de listagem
de usuários
409 - Conflict - Uma requisição de criação ou atualização de um
recurso com um valor de um campo que já existe em outro recurso.
Por exemplo, um nome de usuário duplicado.
Status 5XX representam erros do lado do servidor, que por algum motivo não conseguiu processar a requisição. Para estes retornos deve ser contatado os responsáveis pelo serviço para identificar o que ocorreu.
500 - Internal Server Error - Ocorreu algum erro no processamento
da requisição
502 - Bad Gateway - Ocorreu algum erro de comunicação entre os
componentes da API
503 - Service Unavailable - O serviço está indisponível devido a
uma atualização ou devido a quantidade excessiva de requisições do cliente
504 - Gateway Timeout - Ocorreu um timeout no processamento da requisição
por parte da serviço provedor da API