REST API Design & Minimal APIs
Principios REST, Status Codes, Controllers, Minimal APIs, Versionamento e Filters no ASP.NET Core
REST nao e um protocolo — e um estilo arquitetural. HTTP e o protocolo. Uma API pode usar HTTP sem ser RESTful, e uma API RESTful sempre usa HTTP como transporte.
Principios REST
REST (Representational State Transfer) foi definido por Roy Fielding em 2000. Sao 6 constraints arquiteturais:
| Principio | Descricao | Impacto pratico |
|---|---|---|
| Stateless | Cada request contem toda informacao necessaria — servidor nao guarda sessao | Escalabilidade horizontal: qualquer instancia atende qualquer request |
| Resource-oriented | URIs representam recursos (substantivos), nao acoes (verbos) | /api/products/42 em vez de /api/getProduct?id=42 |
| Uniform Interface | Metodos HTTP padrao para operacoes (GET, POST, PUT, DELETE) | Previsibilidade — qualquer dev sabe o que esperar |
| HATEOAS | Respostas incluem links para acoes possiveis sobre o recurso | Cliente descobre a API navegando — raro em APIs reais |
| Client-Server | Separacao clara de responsabilidades | Frontend e backend evoluem independentemente |
| Cacheable | Respostas devem indicar se podem ser cacheadas | Headers: Cache-Control, ETag, Last-Modified |
Metodos HTTP
| Metodo | Operacao | Idempotente? | Safe? | Request Body | Exemplo |
|---|---|---|---|---|---|
| GET | Ler recurso | Sim | Sim | Nao | GET /api/products/42 |
| POST | Criar recurso | Nao | Nao | Sim | POST /api/products |
| PUT | Substituir recurso inteiro | Sim | Nao | Sim | PUT /api/products/42 |
| PATCH | Atualizar parcialmente | Nao | Nao | Sim | PATCH /api/products/42 |
| DELETE | Remover recurso | Sim | Nao | Opcional | DELETE /api/products/42 |
Content Negotiation
O cliente indica o formato desejado via header Accept. O servidor responde com o formato ou 406 Not Acceptable.
// Configurar formatters no Program.cs
builder.Services.AddControllers(options =>
{
options.RespectBrowserAcceptHeader = true;
options.ReturnHttpNotAcceptable = true; // retorna 406 se formato nao suportado
})
.AddXmlSerializerFormatters() // suporta Accept: application/xml
.AddJsonOptions(opt =>
{
opt.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
opt.JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
});
// Request com Accept: application/json → JSON
// Request com Accept: application/xml → XML
// Request com Accept: text/csv → 406 Not Acceptable
Qual a diferenca entre PUT e PATCH?
PUT substitui o recurso inteiro — voce envia todos os campos. Se omitir um campo, ele volta ao valor default ou null. PATCH atualiza apenas os campos enviados — os demais permanecem inalterados. PUT e idempotente por definicao (mesma request = mesmo resultado). PATCH tecnicamente nao e idempotente (ex:
{ "op": "increment", "path": "/views" }). Na pratica, a maioria das APIs usa PATCH como se fosse idempotente (partial update simples).