Nos ultimos artigos debatemos sobre padronização de API's com REST, as motivações. As boas práticas, mas nenhum exemplo de código. Neste artigo iremos criar uma API RESTFul, seguindo boas práticas!

Já te disseram que sua API não deveria retornar 200 Ok em caso de erro de negócio? Ou então que deveria usar GET ao invés de POST. Mas ninguém nunca mostrou como fazer!

Neste tutorial será criado uma API seguindo os padrões RESTFul. Será utilizado retorno de erros com ProblemDetails. Utilizando GET, POST, PUT, PATCH e DELETE. Trabalhando os Status Code no retorno da API. E por fim o Swagger.

Os exemplos abaixo estão relacionados com o artigo anterior API RESTful - Boas práticas

Padrões importam

O Uncle Bob no seu livro Clean Code diz que a proporção entre ler código e fazer código é de 10 para 1.

Indeed, the ratio of time spent reading vs. writing is well over 10:1.
Martin, Robert C.. Clean Code (Robert C. Martin Series) . Pearson Education.

Aprender é um processo que gasta muita energia. Repetição é essencial para a vida humana. A humanidade não sobreviveria se tivesse que reaprender tudo todos os dias. Como escovar os dentes, andar e falar. O trânsito seria ainda mais caótico, se todos os dias você entrasse no carro e tivesse que reaprender todos os detalhes de como dirigir, acelerar, pisar na embreagem, trocar de marcha.

A repetição armazena o conhecimento, há um momento que você já troca de marcha automaticamente. Você anda sem se questionar como faz isso. Se tornou natural, intrínseco as atividades diarias.

Seguir padrões em times de desenvolvimento de software significa repetir. Você pode trocar de time, ou projeto e o esforço para aprender será menor, pois as boas práticas e padrões estão sendo repetidos. E trilhar um caminho conhecido te permite explorar os detalhes que importam: O negócio.

LED-Keyboard

Swagger

O Open API permite explorar sua API através de uma interface, facilitando o teste e permitindo que outros componentes interajam com sua API mais facilmente.

Pressione o botão direito no projeto e em seguida vá até a opção Manage Nuget Packages. Procure por Swashbuckle.AspNetCore e instale o pacote.

Abra o Startup.cs e adicione a seguinte configuração em ConfigureServices

A configuração acima configura e adiciona o Swagger.

swagger-2

Filtrar, paginar e ordenar

Considere a seguinte request: GET /users?status=active&lives_in=brazil&older_than=18&younger_than=35&sort=firstname,-lastname&limit=10. Ela possui os seguintes parâmetros:

  • Status=active
  • lives_in=brazil
  • older_than=18
  • younger_than=35
  • sort=firstname (asc),-lastname(desc)
  • limit=10
  • Offset=20

Abaixo como lidar com esses parâmetros de forma prática

Para implementar esses filtros no ASP.NET Core será utilizado a biblioteca AspNet.Core.RESTFul.Extensions.

Crie uma classe que tenha todos os parâmetros desejados.

E na Controller utilize essa classe como parâmetro do GET.

O atributo [FromQuery] indica ao ASP.NET Core que todos os atributos da classe estarão disponíveis como QueryString.

Responses - Status Code & ProblemDetails

As respostas vão seguir esse padrão:

  • 200 Ok - Padrão que representa sucesso. Resposta padrão para GET, quando há resultados.
  • 201 Created - Indica que um recurso foi criado. Utilize para a resposta do POST.
  • 204 No Content - Representa que a request foi processada com sucesso, mas não há conteúdo para ser retornado. Utilize para PUT, PATCH e DELETE. E também para situações em que o GET não retornou resultados.
  • 202 Accepted - Indica que o servidor aceitou a request. Esse é um ótimo Status para processos assíncronos. Por exemplo um cenário onde o usuário faz upload de uma planilha que será processada em background.

Em caso de erro nas regras de negócio irão retornar uma classe ProblemDetails

GET

Criando o retorno de um GET

POST

Lidando com o POST, há duas situações. A primeira onde é possível obter o recurso criado. Por exemplo, o usuário cria um Ticket e há um GET disponível para recuperar a informações. Segunda situação é caso esse recurso não pode ser recuperado, por exemplo, criar uma senha.

No código acima, caso haja algum problema de negócio na criação do usuário, ele retorna 400 BadRequest.
Caso tenha sido criado com sucesso chama o método CreatedAtAction(...). Esse método retorna o Status Code 201 Created. No body passa objeto criado e adiciona o Header Location com o endereço onde esse recurso pode ser recuperado.

PUT

Um boa forma de lidar com o URI do PUT é similar ao GET. PUT /users/{id}. Este verbo sempre Retorna um NoContent(). Indica sucesso e que não há dados para a resposta.

PATCH

Para trabalhar com o Patch no ASP.NET Core é preciso adicionar a referência Microsoft.AspNetCore.JsonPatch. O tratamento de resposta do PATCH será igual ao PUT. Afinal ambos atualizam a informação. Enquanto o PUT atualiza TODA a informação o PATCH atualiza parcialmente.

DELETE

O tratamento de Resposta do DELETE é semelhante ao PUT/PATCH.

Download

O código do projeto está disponível no meu GitHub

Conclusão

Espero que esse artigo te ajude e colabore com seu conhecimento.

Deixe seu comentário!