No último artigo eu apresentei a anatomia de uma API RESTFul, ou seja, os principais conceitos e termos necessários para entender o funcionamento básico de uma API.
Agora é o momento de nos aprofundarmos, então nesse artigo vou apresentar mais sobre o protocolo HTTP, seus métodos e os códigos de status.
Mas antes, para iniciarmos, vou esclarecer para que cada um serve.
O HTTP, ou, HyperText Transfer Protocol é o protocolo de comunicação de dados do mundo da internet (Web). Em outras palavras, ele facilita e define os padrões de comunicação dos dados entre um Webbrowser e um Web server.
Quando falamos de métodos eles basicamente são ações permitidas dentro de uma API. E ao falar de códigos de status, eles são os retornos padrões de uma API. E ambos fazem parte das definições do protocolo HTTP.
Agora sim, vamos nos aprofundar mais sobre esses métodos e códigos de status permitidos na utilização desse protocolo.
Métodos
Vamos falar basicamente dos 5 principais, e que provavelmente será os que você irá passar 99% do seu tempo como desenvolvedor.
O método GET
Esse será o método que você mais irá utilizar, pois ele é utilizado para buscar dados em APIs.
A ideia dele é simples, você utiliza uma estrutura de Query String para enviar os parâmetros da sua consulta e o servidor retorna os dados em caso de sucesso, ou caso você não envie a Query String na URL, a API irá retornar todos os dados sem o filtro.
Se você não sabe o que é Query String, dê um passo para trás e leia meu último artigo sobre a anatomia de uma API.
Vamos continuar o exemplo de uma API que traz dados sobre gastronomia e sua URL base é https://api.minhagastronomia.com.
Como desenvolvedor eu gostaria de consultar dados sobre vinhos brancos de até 100 reais.
Então eu faria a requisição — GET https://api.minhagastronomia.com/vinhos?ate_preco=100&tipo=branco
Lembrando que a API teria que fornecer os parâmetros da Query String (ate_preco e tipo) em sua documentação para utilização na requisição.
Ou então, imaginem que eu já tenho a lista de vinhos devido a minha última requisição, e quero me aprofundar mais em um vinho específico que tem o identificador único 22.
Nesse caso, eu faria a requisição abaixo, no qual, o 22 seria o valor do parâmetro {id} da URL. — GET https://api.minhagastronomia.com/vinhos/22
Nesse caso, não é utilizada uma Query String, e sim um parâmetro de URL, pois o {id} é obrigatório.
O método POST
Agora pense que você não encontrou um vinho que gosta, e gostaria de cadastrar esse vinho nessa API, nesse caso, você utilizaria o método POST, e enviaria os dados desse novo vinho no corpo (Body) da requisição, por exemplo:
POST https://api.minhagastronomia.com/vinhos com o body:
{
“nome”: “Maycas Reserva Sumaq Chardonnay 2016”,
“preco”: 49,
“pais”: “Chile”,
“recomendado”:”peixe, frutos do mar”,
“tipo”: “branco”
}
E pronto, você acabou de cadastrar um novo vinho.
Os métodos PUT e PATCH
O método PUT é utilizado em cenários de criação e atualização de dados, ou seja, se eu enviasse o vinho e ele já existisse, então ele apenas seria atualizado, caso contrário, seria criado um novo vinho.
OBS: Lembrando que isso é uma recomendação do protocolo e que tudo depende do desenvolvedor implementar ou não.
Por sua vez, o método PATCH serve para atualizações parciais daquele registro, ou seja, vamos imaginar que aquele vinho cadastrado gerou o identificador 55, e que agora eu gostaria de atualizar apenas o preço dele, a requisição ficaria dessa forma:
PATCH https://api.minhagastronomia.com/vinhos/55 com o body:
{“preco”: 49}
O método DELETE
Como o próprio nome já diz, o método DELETE é o responsável por deletar os registros.
Portanto, supondo que você queira deletar o mesmo vinho que você acabou de atualizar, você faria a seguinte requisição:
PATCH https://api.minhagastronomia.com/vinhos/55
Outros métodos
Existem também outros métodos como OPTIONS, HEAD e TRACE que raramente são utilizados, mas caso queira ver a lista completa, clique aqui.
Códigos de status
Agora vamos aos códigos de status permitidos pelo HTTP, e que podem ser agrupados por tipo. Esses códigos são retornados pelo servidor, e servem para informar ao desenvolvedor o que aconteceu após a sua requisição.
Grupo 1
Grupo de status que dá respostas informativas, existem poucas e raramente são utilizadas.
Grupo 2
Grupo de status utilizado em caso de sucesso na requisição. Os mais utilizados desse grupo são:
200 OK — Código mais utilizado, e que indica que a requisição foi processada com sucesso.
201 Created — Indica que a requisição foi bem sucedida e que um novo registro foi criado como resultado. Resposta utilizada em requisições do método POST.
Grupo 3
Define respostas de redirecionamento. São utilizadas com o intuito de informar o cliente sobre mudanças na requisição e o redirecionamento para uma nova URL. Esses são os mais comuns:
301 Moved Permanently — Informa que o recurso A agora é o recurso B, de forma que quando o cliente solicitar o recurso A ele será automaticamente encaminhado ao recurso B.
304 Not Modified — Resposta utilizada em cenários de cache. Informa ao cliente que a resposta não foi modificada, e nesse sentido, o cliente pode usar a mesma versão em cache da resposta.
307 Temporary redirect — Se trata de um redirecionamento de uma página para outro endereço, porém que é com caráter temporário, e não permanente.
Grupo 4
Preste bastante atenção aqui, pois esse grupo informa os erros do lado do cliente. Em outras palavras, caso você monte a requisição de forma incorreta, o servidor irá retornar um erro desse grupo. Vamos aos principais:
400 Bad Request—Essa resposta significa que o servidor não consegue entender sua requisição, pois existe uma sintaxe ou estrutura inválida.
401 Unauthorized — Erro que informa que existe uma camada de segurança no recurso solicitado ao servidor, e que você não está utilizando as credenciais corretas nessa requisição. Lembrando que as credenciais podem ser algo como usuário e senha, token, etc. E tudo vai depender da API que você estará consumindo.
403 Forbidden — Nesse caso as credenciais do cliente são reconhecidas, porém o servidor informa que ele não tem os direitos de acesso necessários para aquele recurso
404 Not Found — Código que informa que o servidor não encontra o recurso solicitado pelo cliente.
429 Too Many Requests — Não é tão comum, mas pode ser utilizado para informar ao cliente que ele excedeu o limite permitido de requisições.
Grupo 5
Tão importante quanto o grupo 4, nesse grupo estão os erros do lado do servidor. Em outras palavras, pensem que nesse caso a requisição foi feita corretamente pelo lado do cliente, porém houve um erro de processamento no servidor. Vamos aos principais códigos desse grupo:
500 Internal Server Error — Erro mais genérico desse grupo e muito utilizado. Ele informa que o servidor encontrou um cenário inesperado de erro que não soube tratar, e por isso não conseguiu retornar uma resposta na requisição do cliente.
503 Service Unavailable — Erro normalmente utilizado para informar que o servidor está fora do ar, em manutenção ou sobrecarregado.
Existem diversos códigos de status disponíveis para uso no protocolo HTTP, mas sem dúvidas, nesse artigo eu citei os que são mais utilizados.
Caso você queira ver a lista completa, é só clicar nesse link.
Hey amigos hackers =) chegamos ao fim de mais um artigo sobre APIs.
Conclusão sobre métodos e códigos do HTTP
Se você gostou, curta e compartilhe, dessa maneira você ajuda a impactar vários outros desenvolvedores que podem precisar desse conteúdo.
Aproveite para conferir nossos outros artigos sobre APIs!
