Criando padrões de resposta em suas APIs com ASP.NET Core

Fala Galera!

Neste primeiro post do ano, venho trazendo uma dica muito legal do ASP.NET Core. Temos situações que precisamos retornar dados de resposta de nossas APIs em alguns formatos como por exemplo camelCase. 

Existem algumas formas de se retornar os dados de sua APIs, para melhorar a padronização de suas respostas devemos sempre retornar em camelCase porém existem outras convenções são elas:

• PascalCase – Convenção para retornar os dados com a primeira letra maiúscula. Nome compostos também entram neste regra. Por exemplo: NomeCompleto, DataNascimento, EnderecoCompleto, esse é o padrão de resposta do ASP.NET Core
• camelCase – Convenção para retornar os dados com a primeira letra minúscula e a segunda parte maiúscula. Por exemplo: nomeCompleto, dataNascimento, enderecoCompleto.
• snake_case – Convenção para retornar os dados com um underline entre as palavras e todas as letras minúsculas. Por exemplo: nome_completo, data_nascimento, endereco_completo.

Retornando respostas no padrão camelCase

Para conseguimos retornar dados no formato camelCase basta alterar o startup.cs e adicionar o seguinte código conforme o exemplo abaixo:

public void ConfigureServices(IServiceCollection services)
{
   services.AddControllers().AddJsonOptions(o =>
   {
      o.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
      o.JsonSerializerOptions.IgnoreNullValues = true; //Caso queira ignorar os valores nulos, basta configurar para true
   });
 }

Veja a resposta no Postman na imagem abaixo:

Veja na imagem acima que nossa API está retornando as resposta na convenção camelCase

Adicionando outros formatos de respostas como XML

Algumas vezes precisamos que nossas APIs retornem em outros formatos de respostas além do JSON, um exemplo desse é o formato XML e para que possamos fazer isso de forma global para nossas APIs basta fazer algumas configurações no startup.cs. 

Para habilitar outros formatos de forma automática, adicione o código abaixo:

services.AddControllers(o =>
{
     o.OutputFormatters.RemoveType<StringOutputFormatter>();
     o.OutputFormatters.RemoveType<HttpNoContentOutputFormatter>();
     o.FormatterMappings.SetMediaTypeMappingForFormat("xml", MediaTypeHeaderValue.Parse("application/xml"));
     o.FormatterMappings.SetMediaTypeMappingForFormat("json", MediaTypeHeaderValue.Parse("application/json"));
}).AddJsonOptions(o =>
{
     o.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
     o.JsonSerializerOptions.IgnoreNullValues = true;
}).AddXmlSerializerFormatters();

Nesta configuração, estamos adicionando o formato XML e fazendo o mapeamento na sua URL.

Para isso estamos utilizando o FormatterMappings para caso o cliente passe o formato especificado e retorne XML ou JSON. Também estamos removendo o StringOutputFormatters e o HttpNoContentOutputFormatter. 

Mas porque estamos removendo os dois? Simples, sem o StringOutputFormatter, o formatador padrão de JSON, caso o ASP.NET Core não encontre um formatador para o JSON, ele tentará utilizar o formatador XML caso esteja disponível. Se o XML não estiver disponível o ASP.NET Core não saberá como responder e voltará um HttpStatusCode 406 Not Acceptable. 

Já no caso do HttpNoContentOutFormatter trataremos os caso de nulos:

• Quando a resposta for JSON, a resposta nos objetos em caso de nulo será null
• Quando a resposta for XML, a resposta nos objetos em caso de nulo será xsi:nil=”true” como atributo do objeto

Com o nosso startup.cs configurado devemos ir na nossa API e colocar o Atributo FormatFilter, ele que ativará a respostas em outros formatos coloque o atributo conforme exemplo abaixo:

[ApiController]
[Route("[controller]")]
[FormatFilter]
public class WeatherForecastController : ControllerBase
{
   //Codigos de API
}

 

Pronto, tudo configurado! Vamos testar =]

Veja a resposta no Postman para uma saída no formato XML, basta colocar os Headers necessários em nossa requisição conforme imagem abaixo:

Também é possível utilizar uma Querystring com o nome “format” e formato que deseja que a API responda. Por exemplo se quiser o formato XML basta colocar “?format=xml” confira na imagem abaixo:

Caso precise voltar no padrão JSON basta suprimir a Querystring e sua APIs voltará a resposta como JSON, confira na imagem abaixo:

Conclusão

Assim chegamos ao final do nosso post, mostrando como é possível de forma simples padronizar as respostas e os formatos de nossas API.

Espero que tenham gostado.

Não deixe de comentar o que achou deste post =]

Abs e até a próxima.