by Bruno Brito on 26 de Janeiro de 2020 Read in 4 min
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
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.
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.
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:
lives_in=brazil
older_than=18
younger_than=35
sort=firstname (asc),-lastname(desc)
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:
201 Created - Indica que um recurso foi criado. Utilize para a resposta do POST.
Em caso de erro nas regras de negócio irão retornar uma classe ProblemDetails
Criando o retorno de um GET
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.
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.
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.