Explicações gerais
Este capítulo tem o intuito de te contextualizar sobre as terminologias utilizadas, uma teoria básica e alguns itens comuns como status code, tipo de respostas, etc…
Este livro não tem o intuito de te ensinar uma teoria básica sobre o assunto REST APIs. Recomendo que você procure algum conteúdo teórico antes de iniciar o próximo capítulo do livro.
Terminologia utilizados
Durante a leitura deste livro você pode se deparar com as terminologias abaixo:
| Terminologia | Descrição |
|---|---|
| Recursos | É o nome dado a abstração da API |
| endpoint | Indica acesso a um recurso, geralmente uma URL |
| Métodos | Indica as interações permitidas (GET, POST, PUT, etc…) |
| Parâmetros | São opções que possamos passar ao endpoint para influenciar a resposta |
| Path parameter | São parâmetros que aparecem no endpoint entre chaves. Indica que parâmetro é obrigatório |
| Query Parameter | São parâmetros de pesquisa opcionais que aparecem no endpoint com ?atributo=valor
|
| Request | É a forma enviar informações a fim de obter um resultado. É composto pelo endpoint, método e parâmetros se necessário |
| Response | É a informação retornada após um request. Pode ser apenas o status code ou pode conter uma response body
|
| Response body | São dados retornados pelo request em um formato pré-determinado, geralmente JSON ou XML |
| Status code | São códigos numéricos, pertencentes a especificação HTTP, para identificar comportamentos |
Status Code
São um padrão de códigos utilizados para entender o resultado de uma requisição. Existe uma padronização e uma divisão em cinco (5) categorias:
| Categoria | Descrição |
|---|---|
| 1xx: Informacional | Comunica informações de transferência a nível de protocolo |
| 2xx: Sucesso | Indica que uma requisição do cliente foi aceita com sucesso |
| 3xx: Redirecionamento | Indica que o cliente precisa tomar alguma ação adicional para completar a requisição |
| 4xx: Erro no Cliente | Esta categoria indica os possíveis problemas do lado do cliente |
| 5xx: Erro no Servidor | Esta categoria indica problemas do lado do servidor |
Status code utilizados na aplicação
Os seguintes status code são utilizados na aplicação de backend que utilizaremos para os testes:
| Status code | Descrição | Onde é utilizado |
|---|---|---|
| 200 | Quando obtemos sucesso na ação | Nos verbos GET e PUT
|
| 201 | Quando um recurso é criado com sucesso | No verbo POST
|
| 204 | Quando um recurso não retorna dados, mas a ação foi correta | No verbo DELETE
|
| 404 | Quando um recurso não é encontrado | Nos verbos GET, PUT e DELETE
|
| 409 | Quando há um conflito | Nos verbos POST e PUT
|
| 422 | Quando há falta de informações | No verbo POST
|