restful-api
Diretrizes para APIs REST/HTTP
Contexto
A falta de um padrao para o design e documentacao de APIs REST pode resultar em inconsistencias entre os servicos. Cada equipe implementa aspectos criticos como versionamento, paginacao e, principalmente, a estrutura de respostas de erro de maneira distinta, podendo dificultar integracoes.
Estas divergencias podem acarretar consequencias diretas para o ecossistema de desenvolvimento:
-
Aumento da carga cognitiva: Desenvolvedores que consomem as APIs sao forcados a aprender as particularidades de cada servico, aumentando o tempo de integracao e a probabilidade de erros.
-
Fragilidade do ecossistema: A falta de previsibilidade nas interacoes entre servicos gera integracoes frageis e de dificil depuracao.
O objetivo e instituir boas praticas baseadas na especificacao OpenAPI 3, aliada a uma filosofia "Design-First", como a fundacao de um "manual de estilo" para as APIs.
1. Mapeamento de Endpoints
Utilize ASP.NET Core MVC (Controllers) ou Minimal APIs para mapear os endpoints, escolhendo a abordagem mais adequada para o contexto do projeto.