Documentação de uma API REST

Uma API REST sempre possui uma documentação sobre o seu funcionamento. Normalmente a documentação apresenta como efetuar as requisições com os caminhos (paths) necessários, parâmetros e tipos de retorno. A documentação do projeto de backend foi desenvolvida utilizando Swagger.

Como acessar a documentação da API

Você deve estar com a aplicação iniciada para acessar a documentação.
Ela é disponibilizada através da url + porta + /swagger-ui.html.

Efetue o acesso no endereço http://localhost:8088/swagger-ui/index.html

Explicação da documentação

A partir de agora a explicação sobre cada API será feita associando um número dentro da imagem com uma lista numerada, assim quando você ler sobre um item da lista pode já fazer a associação direta com a imagem.

Na página inicial da documentação você visualizará dois itens:

• Restrições
• Simulações

Eles são chamados de controllers e cada um é responsável por efetuar uma ou mais ações de API para este contexto.

1. Os controllers são listados contendo o seu nome e descrição

Restrição

Este controller possui apenas duas chamadas do tipo GET. O intuito é efetuar uma consulta para saber se o CPF informado possui ou não uma restrição.

Note que há sempre um padrão em toda documentação de cada controller:

1. Método HTTP
2. URL da requisição
3. Descrição da requisição

Quando clicamos sobre a chamada (linha que possui o método HTTP + URL + descrição) podemos visualizar o detalhe da requisição e saber informações importantes como:

1. Parâmetros
2. Respostas

Parâmetros

Os parâmetros podem ser ou não informações obrigatórias. Há dois tipos de parâmetros:

• path parameter: onde inserimos o valor diretamente na URL
• query parameter: onde inserimos o atributo e o valor diretamente na URL

No exemplo das Restrições temos um path parameter. Este tipo de parâmetros é representado pelo nome do parâmetro dentro de chaves. Exemplo: {cpf}.

A sessão Parameters apresenta quais são os parâmetros existentes, sendo composto por:

1. nome do atributo
2. tipo de dados + tipo do parâmetro
3. obrigatoriedade
4. descrição

Respostas

As respostas não muito importantes no contexto de desenvolvimento e testes. Elas presentam comportamentos frente a fluxos principais (esperados), fluxos de exceção e regras de negócio.

Devemos prestar atenção em dois itens:

• Code: Status code do retorno da requisição
• Example Value: é o retorno esperado (Response Body)

No exemplo abaixo vemos:

1. O Code (status code) como 200 para uma pessoa que possui restrição
2. O exemplo de retorno (Response Body) como

{
  "mensagem": "O CPF 999999999 não foi encontrado"
}

* Logo, quando efetuarmos uma requisição para um CPF que possui uma restrição, receberemos estas duas informações.

3. O Code como 404 para uma pessoa que não possui restrição e sem retorno (sem Response Body)

Observação

Há um outro método GET na API de Restrição que será explicado em outro capítulo

Comumente referenciamos estas requisições pelo verbo seguido da URL que, neste caso, apresenta apenas o contexto que deve ser alcançado. Em outras palavras: na documentação da API o nome ou IP do servidor não é apresentado.

Exemplo:

GET /api/v1/restricoes/{cpf}

A leitura desta linha pode ser feita da seguinte forma: uma requisição do tipo GET para a API de Restrições, onde devemos informar o cpf como parâmetro.

A partir de agora a explicação para os próximos endpoints serão feitos desta maneira.

Simulações

A simulação é um CRUD (Create, Restore, Update e Delete) onde podemos inserir uma simulação de crédito. Note que na simulação existem diferentes requisições, uma para cada ação de CRUD.

GET /api/v1/simulacoes

Esta requisição retorna todas as simulações existentes. Note que, o Example Value (referência número 2 na imagem) inicia o exemplo com colchetes. Isso quer dizer que o retorno é um array de elementos (simulações). Quando existir mais de uma simulação cadastrada ela será separada por vírgula após o fechamento das chaves. Exemplo:

Você pode notar também que há um parâmetro (referência 1 na imagem acima) não obrigatório, do tipo query com o nome nome.
Falaremos sobre query parameters (parâmetros de consulta) mais tarde em um exercício.

GET /api/v1/simulacoes/{cpf}

Esta requisição retorna uma simulação existente dado um CPF, logo podemos ver que o CPF é obrigatório. Veja o item 1 da imagem.

Note que, quando a simulação é encontrada o status code é 200 e o retorno (response body) é um objeto de simulação. Veja item 2 da imagem.

Se a simulação para o CPF desejado não existir, o status code deverá ser 404 e nada será retornado no response body. Veja o item 3 da imagem.

POST /api/v1/simulacoes

Esta requisição cria um recurso (neste caso uma simulação).

Note o seguinte na sessão Parameters:

1. O parâmetro esperado é uma simulacao e o tipo é um body.
2. Quando isso acontecer você deve enviar os mesmos atributos contidos no Exemple Value
3. O tipo de dados deve ser igual ao item contido no campo Parameter content type. Neste caso um application/json, ou seja, enviaremos um objeto JSON

Note também que há diferentes retornos na seção Responses.

Quando a simulação for criada com sucesso notamos que:

1. O status code retornado deve ser 201
2. Não há respose body, logo não precisamos validá-lo
3. É retornado o atributo Location no Header

O atributo Location provê informações sobre a localização de um recurso criado recentemente.
No nosso contexto de API esta informação é a URL completa do recurso que podemos localizar.

Exemplo:

Digamos que criamos um recurso com o CPF 12345678901.
O Location retornado será http://localhost:8088/api/v1/simulacoes/12345678901, exatamente a URL que podemos utilizar para consultá-lo através de uma requisição GET.

Existem outros dois retornos na seção Responses.

1. Recebemos o status code 409 quando o CPF do objeto que estamos enviando já existe
2. Recebemos o status code 422 quando existe a falta de alguma informação ou alguma regra de negócio é violada

O item 1, status code 409, não possui retorno.
Já o item 2 possui o response body como um array e, dentro dele, um atributo erros. Este atributo possui uma série de propriedades e valores que é composto pelo nome do atributo que falta informação ou viola alguma regra de negócio.

Exemplo:

{
    "erros": {
        "parcelas": "Parcelas deve ser menor ou igual a 48",
        "valor": "Valor deve ser menor ou igual a R$ 40.000",
        "email": "must be a well-formed email address"
    }
}

PUT /api/v1/simulacoes/{cpf}

Esta requisição atualiza algum atributo (dado) de uma simulação existente. A chave de pesquisa da simulação existente é o CPF.

Você pode alterar todos os atributos ou somente os que você escolher.

1. Devemos informar o cpf como chave de pesquisa como um path parameter
2. Devemos informar o objeto simulacao
3. Este objeto pode ser os atributos descritos no Example Value
4. O tipo de conteúdo deve ser application/json

A documentação do PUT apresenta três possíveis retornos:

1. Quando a alteração for executada com sucesso o status code será 200
2. O response body da simulação alterada com sucesso traz todos os atributos da simulação mesmo se não tiverem sido alterados
3. Quando a alteração para a simulação com CPF desejado não existir, o status code será 404
4. Se enviarmos uma simulação com um CPF alterado, e este já existir, o retorno será o status code 409

DELETE /api/v1/simulacoes/{cpf}

Esta requisição remove uma simulação existente. A chave de pesquisa da simulação existente é o CPF.

1. Para remover a simulação devemos informar o cpf como parâmetro no path (path parameter)

O DELETE tem dois possíveis retornos:

1. O status code 204 quando a simulação foi removida com sucesso
2. O status code 404 quando uma simulação com o CPF informado não foi encontrado