Já te disseram que sua API não deveria cuspir um 200 OK quando tudo deu errado na regra de negócio?

Tipo, o cliente não existe, o pagamento falhou, o estoque tá negativo, mas lá está o 200 firme e forte, como se o servidor estivesse em negação? E aquele POST que você usou pra buscar dados, porque “o GET tava dando trabalho”? Pois é.

Mas relaxa, ninguém nunca te mostrou como fazer certo, só te apontaram o dedo e mandaram um link do Stack Overflow de 2013.

Neste tutorial, vou te mostrar como fazer uma API RESTful de verdade, ou pelo menos algo que não cause dor física em quem consome. Vamos usar o tal do ProblemDetails, aquele formato chique pra te dizer que deu ruim, mas com elegância. GET, POST, PUT, PATCH, DELETE... todos na mesa, cada um com seu papel. Sim, GET não serve pra alterar, por mais que sua pipeline aceite.

Vamos tratar status code como gente grande: nada de 200 OK com corpo dizendo "erro". Se deu ruim, assume. Joga um 400, um 422, um 404, sei lá, mas joga o certo. E claro, tudo documentado no Swagger, porque se não tá no Swagger, nem existe.

Ah, os exemplos abaixo estão conectados com aquele outro artigo onde tentei ensinar boas práticas(APIs RestFul - Boas Práticas). Mas sei que metade pulou direto pros exemplos achando que REST é só decorar verbos HTTP.

Padrões importam, sim senhor

O tal do Uncle Bob já mandou a real: você passa 10x mais tempo lendo código do que escrevendo. Mas tem dev que ainda insiste em inventar moda a cada novo método, como se fosse escrever o próximo framework revolucionário da humanidade.

Aprender exige energia, e a repetição é o jeitinho que o cérebro encontrou pra não falhar miseravelmente todo dia. Você não reaprende a dirigir toda vez que entra no carro, né? Mesma coisa no código. Quando os padrões são respeitados, a cabeça trabalha no automático pro que importa: o negócio.

Seguir padrão não é caretice, é sobrevivência. Time muda, projeto muda, mas se todo mundo fala a mesma “linguagem”, ninguém precisa fazer curso de decodificação só pra entender onde tá o maldito try-catch. Repita. Padronize. Automatize o básico pra sobrar espaço mental pra resolver problema de verdade.

LED-Keyboard

Swagger

O tal do OpenAPI, conhecido nas rodas de conversa como Swagger, é aquela interface bonitinha que deixa sua API menos misteriosa. Serve pra testar endpoints sem precisar escrever 500 linhas de curl, e ainda ajuda outros sistemas a entender como falar com sua aplicação sem precisar de bola de cristal.

Pra adicionar isso no seu projeto .NET, faz o básico: botão direito no projeto, vai em Manage NuGet Packages, procura por Swashbuckle.AspNetCore e instala. Simples, sem precisar chamar o arquiteto.

Depois, abra o Startup.cs e joga essa configuração em ConfigureServices:

Essa mágia negra aí configura o Swagger pra sua API. A partir disso, você ganha uma UI amigável, que te mostra os endpoints, os parâmetros, os retornos e até os erros, isso se você for civilizado o suficiente pra documentar corretamente.

swagger-2

swagger-2

Agora não tem desculpa pra não fazer doc.

Filtrar, paginar e ordenar

(ou como evitar fazer SELECT * FROM no século XXI)

Você ainda tá mandando todos os dados do banco pra tela e esperando que o front resolva na base do Array.filter()? Parabéns, você reinventou o lag.

Agora olha essa requisição decente: GET /users?status=active&lives_in=brazil&older_than=18&younger_than=35&sort=firstname,-lastname&limit=10&offset=20 Ela é quase poesia, e tem tudo que uma API que se preze precisa:

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

Com isso, o front não precisa puxar 30 mil registros pra mostrar 10.

Pra implementar isso no ASP.NET Core, a gente vai usar a biblioteca AspNetCore.IQueryable.Extensions. Ela existe pra te impedir de fazer um if pra cada parâmetro e acabar com 3 mil linhas de código só pra listar usuários.

Primeiro, crie uma classe que represente todos os filtros civilizadamente:

Depois, na Controller, usa essa classe como parâmetro do seu método GET. Simples, limpo e sem gambiarra com HttpContext.Request.Query["algo"].

O atributo [FromQuery] é o que diz pro ASP.NET Core: "ó, pega tudo da query string e joga aqui nessa classe". Assim ninguém precisa ficar manualmente buscando parâmetro por parâmetro como os Maias faziam.

Responses — Status Code & ProblemDetails

(Para você parar de devolver 200 até quando tudo está pegando fogo)

Chega de responder com 200 OK até quando tudo que sua API entrega é dor e arrependimento. Vamos dar nome aos bois e usar os status code como foram planejados — e não como se fossem enfeite.

Segue o protocolo civilizado:

  • 200 OK — Sucesso. Padrãozinho pra GET com retorno. Se o servidor entendeu e entregou o que pediram, é ele.
  • 201 Created — Usado quando o POST realmente cria alguma coisa. E sim, ele vem com um cabeçalho Location apontando pro recurso criado, não com um print do banco.
  • 204 No Content — A request foi processada com sucesso, mas não tem nada pra devolver. Ótimo pra PUT, PATCH, DELETE, e até GET que não achou nada. Não precisa devolver uma lista vazia só pra ocupar espaço.
  • 202 Accepted — Requisição aceita, mas ainda vai ser processada. Ideal pra processos assíncronos, tipo upload de planilha que vai explodir o sistema em background.

Agora, quando der ruim de verdade (sim, regra de negócio quebrada é erro), a gente retorna um ProblemDetails, porque jogar só um "Erro genérico" no corpo com 200 OK devia dar cadeia.

GET

Vamos ver o básico do GET, com retorno digno:

POST

O POST tem duas situações:

  1. O recurso pode ser recuperado depois (GET /ticket/123) — usa o CreatedAtAction(...) e devolve o 201 Created.
  2. O recurso não pode ser lido depois (tipo uma senha nova) — aí devolve só 204 ou no máximo um 200, sem exposição.

Se der ruim na regra de negócio, solta um 400 BadRequest com um ProblemDetails. Se der certo, manda o 201 Created com o corpo e o Location no header. Simples.

PUT

URI no estilo REST: PUT /users/{id}. Atualiza tudo, não inventa de usar pra parcial. Retorna sempre NoContent(), porque ninguém quer que você devolva o objeto inteiro depois da atualização.

PATCH

Atualização parcial — o PUT dos preguiçosos. Precisa da lib Microsoft.AspNetCore.JsonPatch, senão o ASP.NET Core fica olhando torto. Resposta igual ao PUT: 204 No Content.

DELETE

Apagar é fácil. A resposta também. Retorna um 204 No Content e fim de papo. Não precisa escrever um poema explicando que o item foi deletado.

Download

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