[Gov.Doc-API] Implementar middleware personalizado

A. Introdução

Para facilitar novas integrações com o Gov.Doc-API, propõem-se implementar middleware personalizado na mesma, pois é um padrão utilizado em todo o mundo nas aplicações independentemente das tecnologias utilizadas. Assim sendo, objetivo desse estudo é analisar as possibilidades de implementação, identificar as possíveis alterações e levantar as demandas necessárias.

1. O que é middleware

"[É o componente que] podemos usar para interceptar a solicitação, e assim, modificá-la enquanto ela passa pelo sistema. Os componentes de middleware, organizados em uma cadeia, formam o pipeline de solicitação. Esses componentes são escritos (ou registrados) no método “Configure” da classe “StartUp”. Neste caso, existem basicamente dois tipos de componentes de middleware. Componentes de middleware padrão (integrados) e personalizados." (Jesus, Daniel)

"Em termos práticos, middleware seria um trecho de código que pode ser executado no fluxo de execução da aplicação. [São]  organizados em um pipeline e são executados conforme uma solicitação é recebida e uma resposta enviada. A imagem abaixo ilustra este pipeline:" (Nascimento, Wladimilson)

É possível definir middleware de diversas funcionalidades, por exemplo, no trecho de código abaixo, temos oito middlewares:

1. Exception/error handling	2. HTTP Strict Transport Security Protocol	3. HTTPS redirection	4. Static file server
5. Cookie policy enforcement	6. Authentication	7. Session	8.MVC

2. Exemplos de implementação

Se é uma API que possui várias integrações ou se tem grande impacto nos sistemas que integram com ela, é de grande valia implementar o versionamento. O mesmo, permite que ao longo das alterações que a API sofre, você possa gradualmente descontinuando funcionalidades e permitindo que novas implementações não impactem integrações existentes com a API. O melhor momento para implementação é na criação da API.

Descrição	Código
1. Configura na Startup
2. Criando a classe Middleware
3. A chamada pode ser usando .UseMiddleware
4. Mas o recomendado é criar um método de extensão e utiliza-lo no Configure()
Cria endpoint configurado para gerar exceção.                             Cria um DTO para estruturar o retorno de exceções.                                       Cria a classe middleware para tratar/padronizar o tratamento/retorno de erros.                                                       Configura na Startup o middleware criado.

3. Alterações necessárias 

A sugestão é utilizar o middleware para tratar e padronizar os erros.

Status HTTP: 500 - Internal Server Error
Retorno: { mensagens: [ "mensagem de validação 1", "mensagem de validação 2"] }

Mas seria necessário fazer um protótipo para tentar padronizar o retorno de validações.

Status HTTP: 400 - Bad Request
Retorno: { mensagens: [ "mensagem de validação 1", "mensagem de validação 2"] }

E padronizar o retorno de bem-sucedido tanto de criação (201 - Created) quanto qualquer outro (200 - OK).

Status HTTP: 200 - OK
Retorno: { mensagem: "mensagem de bem-sucedido" }
         ou { mensagem: "mensagem de bem-sucedido", objeto: { } }

Status HTTP: 201 - Created 
Retorno: { mensagem: "mensagem de bem-sucedido", objeto: { } }

Uma ideia seria criar um BaseService onde elaboraremos uma estrutura que permita adicionar mensagens de validação e antes de realizar a ação, verifica se caiu em alguma validação e retorna o BadRequest. Ou pode criar uma classe de exceção para BadRequest onde quando for gerado essa BadRequestException, usa um middleware para padronizar/formatar o retorno.

Para a questão do bem-sucedido, pode apenas ser criado um dto { mensagem: string, objeto: object } que o Service retornará para controller que retornará return Ok(dto);

B. Conclusão

Concluímos que essas são alterações necessárias para implementar o middleware personalizado e que irá agregar grande valor para as APIs que aplicarem. Facilitará novas integrações, tanto no tratamento quanto no entendimento dos retornos.

Fontes

1. "Aprendendo os componentes de Middleware do Asp .Net Core -Parte 1", Daniel Jesus.
   
2. "Compreendendo os middlewares no ASP.NET Core", Wladimilson M. Nascimento.
3. "Criando um middleware customizado para ASP.NET Core", Wladimilson M. Nascimento.
4. "Padrões de Web API – Parte 02: Middleware", Kenerry Serain.