Design de APIs REST: Verbos HTTP e Parameter Binding

1
2
3
4
5
6

POST /api/getPedidos
POST /api/createUsuario
GET  /api/deletarProduto?id=42
POST /api/updateStatusPedido
POST /api/buscarProdutosPorCategoria
GET  /api/ativarConta?userId=10

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

GET    /api/pedidos              → lista pedidos
POST   /api/pedidos              → cria pedido
GET    /api/pedidos/{id}         → busca pedido por id
PUT    /api/pedidos/{id}         → substitui pedido completo
PATCH  /api/pedidos/{id}         → atualiza parcialmente o pedido
DELETE /api/pedidos/{id}         → remove pedido

GET    /api/usuarios/{id}        → busca usuário
GET    /api/usuarios/{id}/status → sub-recurso: status do usuário

GET    /api/produtos?categoria=eletronicos  → filtro via query string

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// ✅ PUT é idempotente: enviar 3 vezes tem o mesmo efeito que enviar 1 vez
// O pedido 42 termina com status "cancelado" em todos os casos
PUT /api/pedidos/42  →  { "status": "cancelado" }
PUT /api/pedidos/42  →  { "status": "cancelado" }  // mesmo resultado
PUT /api/pedidos/42  →  { "status": "cancelado" }  // mesmo resultado

// ❌ POST NÃO é idempotente: cada chamada cria um novo pedido
POST /api/pedidos  →  { "id": 100, ... }
POST /api/pedidos  →  { "id": 101, ... }  // recurso DIFERENTE criado
POST /api/pedidos  →  { "id": 102, ... }  // recurso DIFERENTE criado

// ⚠️ PATCH pode ou não ser idempotente — depende da semântica:
PATCH /api/pedidos/42  →  { "status": "processando" }  // ✅ idempotente
PATCH /api/pedidos/42  →  { "tentativas": "+1" }        // ❌ não idempotente

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

[ApiController]
[Route("api/[controller]")]
public class PedidosController : ControllerBase
{
    private readonly IPedidoService _service;
    public PedidosController(IPedidoService service) => _service = service;

    /// GET /api/pedidos?pagina=1&tamanhoPagina=20&status=aberto
    [HttpGet]
    [ProducesResponseType<PagedResult<PedidoDto>>(StatusCodes.Status200OK)]
    public async Task<IActionResult> Listar(
        [FromQuery] int pagina = 1,
        [FromQuery] int tamanhoPagina = 20,
        [FromQuery] string? status = null,
        CancellationToken ct = default)
    {
        var resultado = await _service.ListarAsync(pagina, tamanhoPagina, status, ct);
        return Ok(resultado);
    }

    /// GET /api/pedidos/42
    [HttpGet("{id:int}")]
    [ProducesResponseType<PedidoDto>(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public async Task<IActionResult> ObterPorId(
        [FromRoute] int id,
        CancellationToken ct = default)
    {
        var pedido = await _service.ObterPorIdAsync(id, ct);
        return pedido is null ? NotFound() : Ok(pedido);
    }

    /// GET /api/pedidos/42/itens
    [HttpGet("{id:int}/itens")]
    [ProducesResponseType<IEnumerable<ItemPedidoDto>>(StatusCodes.Status200OK)]
    public async Task<IActionResult> ListarItens(
        [FromRoute] int id,
        CancellationToken ct = default)
    {
        var itens = await _service.ListarItensAsync(id, ct);
        return Ok(itens);
    }

    /// GET /api/pedidos/buscar?termo=notebook — filtro de texto livre
    [HttpGet("buscar")]
    [ProducesResponseType<IEnumerable<PedidoDto>>(StatusCodes.Status200OK)]
    public async Task<IActionResult> Buscar(
        [FromQuery] string termo,
        CancellationToken ct = default)
    {
        if (string.IsNullOrWhiteSpace(termo))
            return BadRequest("Parâmetro 'termo' é obrigatório.");

        var resultados = await _service.BuscarAsync(termo, ct);
        return Ok(resultados);
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

/// POST /api/pedidos
/// Body: { "clienteId": 1, "itens": [...] }
[HttpPost]
[ProducesResponseType<PedidoDto>(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
[ProducesResponseType(StatusCodes.Status422UnprocessableEntity)]
public async Task<IActionResult> Criar(
    [FromBody] CriarPedidoRequest request,
    CancellationToken ct = default)
{
    if (!ModelState.IsValid)
        return UnprocessableEntity(ModelState);

    var pedido = await _service.CriarAsync(request, ct);

    // 201 + Location header é o padrão REST para criação
    return CreatedAtAction(nameof(ObterPorId), new { id = pedido.Id }, pedido);
}

/// POST /api/pedidos/42/itens — adiciona item ao pedido (sub-recurso)
[HttpPost("{id:int}/itens")]
[ProducesResponseType<ItemPedidoDto>(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<IActionResult> AdicionarItem(
    [FromRoute] int id,
    [FromBody] AdicionarItemRequest request,
    CancellationToken ct = default)
{
    var item = await _service.AdicionarItemAsync(id, request, ct);
    return item is null
        ? NotFound()
        : CreatedAtAction(nameof(ListarItens), new { id }, item);
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

/// PUT /api/pedidos/42
/// Body: pedido completo (TODOS os campos devem estar presentes)
[HttpPut("{id:int}")]
[ProducesResponseType<PedidoDto>(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> Substituir(
    [FromRoute] int id,
    [FromBody] SubstituirPedidoRequest request,
    CancellationToken ct = default)
{
    if (id != request.Id)
        return BadRequest("O id da URL não corresponde ao id do payload.");

    var atualizado = await _service.SubstituirAsync(id, request, ct);
    return atualizado is null ? NotFound() : Ok(atualizado);
}

/// PUT /api/usuarios/10 — substituição completa do usuário
[HttpPut("{id:guid}")]
[ProducesResponseType(StatusCodes.Status204NoContent)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<IActionResult> SubstituirUsuario(
    [FromRoute] Guid id,
    [FromBody] UsuarioRequest request,
    CancellationToken ct = default)
{
    var existe = await _usuarioService.SubstituirAsync(id, request, ct);
    return existe ? NoContent() : NotFound();
}

1
2
3
4

PATCH /api/pedidos/42
Content-Type: application/merge-patch+json

{ "status": "cancelado", "motivoCancelamento": "Cliente solicitou" }

1
2
3
4
5
6
7

PATCH /api/pedidos/42
Content-Type: application/json-patch+json

[
  { "op": "replace", "path": "/status", "value": "cancelado" },
  { "op": "add",     "path": "/motivoCancelamento", "value": "Cliente solicitou" }
]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

// Instalar: dotnet add package Microsoft.AspNetCore.JsonPatch
// Instalar: dotnet add package Microsoft.AspNetCore.Mvc.NewtonsoftJson

// Program.cs — necessário para JSON Patch
builder.Services.AddControllersWithViews()
    .AddNewtonsoftJson(); // JSON Patch requer Newtonsoft.Json

/// PATCH /api/pedidos/42 — Merge Patch (abordagem simples e recomendada)
[HttpPatch("{id:int}")]
[ProducesResponseType<PedidoDto>(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<IActionResult> AtualizarParcial(
    [FromRoute] int id,
    [FromBody] AtualizarPedidoRequest request,  // Apenas campos anuláveis
    CancellationToken ct = default)
{
    var atualizado = await _service.AtualizarParcialAsync(id, request, ct);
    return atualizado is null ? NotFound() : Ok(atualizado);
}

// DTO para Merge Patch: campos nulos = não alterar
public record AtualizarPedidoRequest(
    string? Status,                 // null = não altera
    string? MotivoCancelamento,     // null = não altera
    decimal? Desconto               // null = não altera
);

// No service: atualiza só os campos com valor
public async Task<PedidoDto?> AtualizarParcialAsync(
    int id, AtualizarPedidoRequest req, CancellationToken ct)
{
    var pedido = await _db.Pedidos.FindAsync([id], ct);
    if (pedido is null) return null;

    if (req.Status is not null)
        pedido.Status = req.Status;
    if (req.MotivoCancelamento is not null)
        pedido.MotivoCancelamento = req.MotivoCancelamento;
    if (req.Desconto.HasValue)
        pedido.Desconto = req.Desconto.Value;

    await _db.SaveChangesAsync(ct);
    return pedido.ToDto();
}

/// --- JSON Patch (RFC 6902) — usando Microsoft.AspNetCore.JsonPatch ---
[HttpPatch("{id:int}/json-patch")]
[Consumes("application/json-patch+json")]
[ProducesResponseType(StatusCodes.Status204NoContent)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> JsonPatch(
    [FromRoute] int id,
    [FromBody] JsonPatchDocument<PedidoUpdateModel> patch,
    CancellationToken ct = default)
{
    var pedido = await _service.ObterModelAsync(id, ct);
    if (pedido is null) return NotFound();

    patch.ApplyTo(pedido, ModelState);

    if (!ModelState.IsValid)
        return BadRequest(ModelState);

    await _service.SalvarAsync(id, pedido, ct);
    return NoContent();
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

/// DELETE /api/pedidos/42
[HttpDelete("{id:int}")]
[ProducesResponseType(StatusCodes.Status204NoContent)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
[ProducesResponseType(StatusCodes.Status409Conflict)]
public async Task<IActionResult> Remover(
    [FromRoute] int id,
    CancellationToken ct = default)
{
    var resultado = await _service.RemoverAsync(id, ct);

    return resultado switch
    {
        DeletarResultado.NaoEncontrado => NotFound(),
        DeletarResultado.ConflitoDependencias =>
            Conflict(new { error = "Pedido possui itens vinculados." }),
        _ => NoContent()
    };
}

/// DELETE /api/pedidos/42/itens/7 — remoção de sub-recurso
[HttpDelete("{id:int}/itens/{itemId:int}")]
[ProducesResponseType(StatusCodes.Status204NoContent)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<IActionResult> RemoverItem(
    [FromRoute] int id,
    [FromRoute] int itemId,
    CancellationToken ct = default)
{
    var removido = await _service.RemoverItemAsync(id, itemId, ct);
    return removido ? NoContent() : NotFound();
}

/// DELETE /api/produtos?ids=1,2,3 — soft delete em lote (use com cuidado)
[HttpDelete]
[ProducesResponseType(StatusCodes.Status204NoContent)]
public async Task<IActionResult> RemoverEmLote(
    [FromQuery] int[] ids,
    CancellationToken ct = default)
{
    await _service.RemoverEmLoteAsync(ids, ct);
    return NoContent();
}

// Enum auxiliar
public enum DeletarResultado { Ok, NaoEncontrado, ConflitoDependencias }

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

[ApiController]
[Route("api/produtos")]
public class ProdutosController : ControllerBase
{
    // GET /api/produtos
    [HttpGet]
    public async Task<IActionResult> Listar(
        [FromQuery] string? categoria,
        [FromQuery] decimal? precoMax,
        [FromQuery] int pagina = 1) { /* ... */ return Ok(); }

    // GET /api/produtos/{id}
    [HttpGet("{id:guid}")]
    public async Task<IActionResult> ObterPorId([FromRoute] Guid id) { /* ... */ return Ok(); }

    // POST /api/produtos
    [HttpPost]
    public async Task<IActionResult> Criar([FromBody] CriarProdutoRequest req) { /* ... */ return CreatedAtAction(nameof(ObterPorId), new { id = Guid.NewGuid() }, req); }

    // PUT /api/produtos/{id}    ← substitui o produto INTEIRO
    [HttpPut("{id:guid}")]
    public async Task<IActionResult> Substituir([FromRoute] Guid id, [FromBody] ProdutoRequest req) { /* ... */ return Ok(); }

    // PATCH /api/produtos/{id}  ← atualiza SOMENTE os campos enviados
    [HttpPatch("{id:guid}")]
    public async Task<IActionResult> AtualizarParcial([FromRoute] Guid id, [FromBody] ProdutoPatchRequest req) { /* ... */ return Ok(); }

    // DELETE /api/produtos/{id}
    [HttpDelete("{id:guid}")]
    public async Task<IActionResult> Remover([FromRoute] Guid id) { /* ... */ return NoContent(); }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

// Rota: GET /api/pedidos/{id}/itens/{itemId}
[HttpGet("{id:int}/itens/{itemId:int}")]
public async Task<IActionResult> ObterItem(
    [FromRoute] int id,       // extrai de {id}
    [FromRoute] int itemId)   // extrai de {itemId}
{ /* ... */ }

// Rota: GET /api/v2/pedidos/{pedidoId}
[HttpGet("~/api/v{versao:int}/pedidos/{pedidoId:guid}")]
public async Task<IActionResult> ObterPedidoVersionado(
    [FromRoute] int versao,
    [FromRoute] Guid pedidoId)
{ /* ... */ }

// Constraints de tipo na rota: :int, :guid, :long, :alpha, :regex(...)
[HttpGet("{id:guid}")]
// [FromRoute] é INFERIDO para parâmetros que combinam com segmentos de rota
public async Task<IActionResult> ObterPorGuid(Guid id)
{ /* ... */ }  // inference automática: funciona sem [FromRoute]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

// GET /api/pedidos?pagina=2&tamanhoPagina=20&status=aberto&ordenarPor=dataCriacao
[HttpGet]
public async Task<IActionResult> Listar(
    [FromQuery] int pagina = 1,
    [FromQuery] int tamanhoPagina = 20,
    [FromQuery] string? status = null,
    [FromQuery] string ordenarPor = "id",
    [FromQuery] bool crescente = true)
{ /* ... */ }

// Listas na query string: GET /api/produtos?ids=1&ids=2&ids=3
// ou com separador: GET /api/produtos?ids=1,2,3
[HttpGet("batch")]
public async Task<IActionResult> ObterEmLote(
    [FromQuery] int[] ids)    // ASP.NET Core resolve ambos os formatos
{ /* ... */ }

// DTO para query string — útil quando há muitos parâmetros de filtro
// GET /api/produtos?categoria=eletronicos&precoMin=100&precoMax=500&emEstoque=true
[HttpGet("pesquisar")]
public async Task<IActionResult> Pesquisar(
    [FromQuery] FiltrosProdutoQuery filtros)
{ /* ... */ }

public record FiltrosProdutoQuery(
    string? Categoria,
    decimal? PrecoMin,
    decimal? PrecoMax,
    bool? EmEstoque,
    string? Termo
);

// Nome de parâmetro diferente do campo C# via [FromQuery(Name = "...")]
[HttpGet("relatorio")]
public async Task<IActionResult> Relatorio(
    [FromQuery(Name = "data_inicio")] DateOnly dataInicio,
    [FromQuery(Name = "data_fim")]    DateOnly dataFim)
{ /* ... */ }

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

// POST /api/pedidos — cria pedido
// Header: Content-Type: application/json
[HttpPost]
public async Task<IActionResult> Criar(
    [FromBody] CriarPedidoRequest request)   // desserializa JSON → C#
{ /* ... */ }

// Múltiplos campos num DTO
public record CriarPedidoRequest(
    [Required] int ClienteId,
    [Required, MinLength(1)] List<CriarItemPedidoRequest> Itens,
    string? Observacoes,
    DateOnly? DataEntregaPrevista
);

// ASP.NET Core com System.Text.Json (padrão) + propriedades obrigatórias
public record CriarItemPedidoRequest(
    [Required] int ProdutoId,
    [Required, Range(1, 9999)] int Quantidade,
    decimal? DescontoUnitario
);

// Validação automática com [ApiController]:
// Se ModelState for inválido, retorna 400 Bad Request automaticamente
// Sem precisar verificar ModelState manualmente

// Configuração global do serializer:
builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        options.JsonSerializerOptions.PropertyNamingPolicy =
            JsonNamingPolicy.CamelCase;         // clienteId, não ClienteId
        options.JsonSerializerOptions.DefaultIgnoreCondition =
            JsonIgnoreCondition.WhenWritingNull; // omite null no output
        options.JsonSerializerOptions.Converters.Add(
            new JsonStringEnumConverter());      // enum como string
    });

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

// POST /api/produtos/imagem — upload de imagem com metadados
// Content-Type: multipart/form-data
[HttpPost("{id:int}/imagem")]
[Consumes("multipart/form-data")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
[RequestSizeLimit(10 * 1024 * 1024)]   // 10 MB máximo
public async Task<IActionResult> UploadImagem(
    [FromRoute] int id,
    [FromForm] IFormFile imagem,         // arquivo
    [FromForm] string? altText,          // campo de texto do form
    [FromForm] bool isPrincipal = false, // flag booleana do form
    CancellationToken ct = default)
{
    if (imagem.Length == 0)
        return BadRequest("Arquivo vazio.");

    var extensoes = new[] { ".jpg", ".jpeg", ".png", ".webp" };
    var ext = Path.GetExtension(imagem.FileName).ToLowerInvariant();
    if (!extensoes.Contains(ext))
        return BadRequest($"Extensão '{ext}' não permitida.");

    await using var stream = imagem.OpenReadStream();
    var url = await _storageService.UploadAsync(stream, imagem.ContentType, ct);

    return Ok(new { url, altText });
}

// Upload de múltiplos arquivos
[HttpPost("importar")]
[Consumes("multipart/form-data")]
public async Task<IActionResult> Importar(
    [FromForm] IFormFileCollection arquivos,  // coleção de arquivos
    [FromForm] string tipo,
    CancellationToken ct = default)
{ /* ... */ }

// DTO para formulário complexo
[HttpPost("cadastro-completo")]
[Consumes("multipart/form-data")]
public async Task<IActionResult> CadastroCompleto(
    [FromForm] CadastroCompletoRequest request)
{ /* ... */ }

public record CadastroCompletoRequest(
    [Required] string Nome,
    [Required, EmailAddress] string Email,
    IFormFile? FotoPerfil    // campo de arquivo opcional
);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

// GET /api/pedidos — com header de correlação e tenant
[HttpGet]
public async Task<IActionResult> Listar(
    [FromHeader(Name = "X-Correlation-Id")] string? correlationId,
    [FromHeader(Name = "X-Tenant-Id")]      string? tenantId,
    [FromQuery] int pagina = 1,
    CancellationToken ct = default)
{
    // Propaga correlation ID para logging e rastreamento distribuído
    using var _ = _logger.BeginScope(new { correlationId, tenantId });
    return Ok(await _service.ListarAsync(tenantId, pagina, ct));
}

// API com versão no header (alternativa ao versioning por URL)
// Header: X-Api-Version: 2
[HttpGet("~/api/relatorios")]
public async Task<IActionResult> Relatorio(
    [FromHeader(Name = "X-Api-Version")] int versao = 1)
{ /* ... */ }

// Exemplo com API key customizada (prefira sempre Authorization padrão)
[HttpPost]
public async Task<IActionResult> WebhookReceber(
    [FromHeader(Name = "X-Webhook-Secret")] string segredo,
    [FromBody] WebhookPayload payload)
{
    if (!_webhookService.ValidarSegredo(segredo))
        return Unauthorized();
    /* ... */
    return Ok();
}

// Útil para Idempotency-Key (pagamentos, operações críticas)
[HttpPost("pagamentos")]
public async Task<IActionResult> ProcessarPagamento(
    [FromHeader(Name = "Idempotency-Key")] string? idempotencyKey,
    [FromBody] PagamentoRequest request,
    CancellationToken ct = default)
{
    if (idempotencyKey is not null)
    {
        var existente = await _cache.GetAsync(idempotencyKey, ct);
        if (existente is not null)
            return Ok(existente);  // resposta idempotente
    }
    /* processa pagamento... */
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

[ApiController]
[Route("api/exemplo")]
public class InferenciaController : ControllerBase
{
    // ASP.NET Core infere automaticamente:
    // - Guid id → [FromRoute] (coincide com {id} na rota)
    // - Request request → [FromBody] (tipo complexo = body por padrão com [ApiController])
    [HttpPut("{id:guid}")]
    public IActionResult Atualizar(Guid id, ProdutoRequest request)
    { /* ... */ return Ok(); }

    // string categoria → [FromQuery] (tipo simples não está na rota = query string)
    [HttpGet]
    public IActionResult Listar(string? categoria, int pagina = 1)
    { /* ... */ return Ok(); }
}

1
2
3
4

https://api.empresa.com/api/produtos/pesquisar
?ids=1,2,3,4,5,...,200          ← ⚠️ pode estourar o limite
&filtros={"categoria":"...", "tags":["a","b",...]}  ← ❌ nunca faça isso
&token=eyJhbGciOiJSUzI1NiIsInR5cCI6...  ← ❌ nunca coloque token na URL

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// Program.cs — ajuste o limite de linha de requisição
builder.WebHost.ConfigureKestrel(options =>
{
    options.Limits.MaxRequestLineSize = 16_384;    // 16 KB (padrão: 8 KB)
    options.Limits.MaxRequestHeadersTotalSize = 32_768; // 32 KB para headers
    options.Limits.MaxRequestBodySize = 10 * 1024 * 1024; // 10 MB para body
});

// Para um endpoint específico com limite maior:
app.MapPost("/api/importar", ImportarHandler)
   .WithMetadata(new RequestSizeLimitAttribute(50 * 1024 * 1024)); // 50 MB

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

// ❌ Problemático: GET com muitos IDs na query string
// GET /api/pedidos?ids=1&ids=2&ids=3... (pode estoura limite)

// ✅ Solução 1: POST para busca complexa (pragmático, não puro REST)
// POST /api/pedidos/buscar
[HttpPost("buscar")]
public async Task<IActionResult> BuscarEmLote([FromBody] BuscarPedidosRequest req)
{ /* ... */ }

public record BuscarPedidosRequest(
    int[]? Ids,
    string? Status,
    DateOnly? De,
    DateOnly? Ate,
    string[]? Tags
);

// ✅ Solução 2: Cursor token encoded em Base64 (para paginação)
// GET /api/pedidos?cursor=eyJpZCI6MTAwLCJkYXRhIjoiMjAyNi0wMS0wMSJ9
// O cursor carrega os critérios de busca serializados e opacamente
[HttpGet]
public async Task<IActionResult> ListarComCursor(
    [FromQuery] string? cursor,
    [FromQuery] int limite = 20)
{ /* desserializa cursor, aplica filtro... */ }

// ✅ Solução 3: Endpoint de lote com body explícito
// POST /api/produtos/lote — busca produtos por lista de IDs no body
[HttpPost("lote")]
public async Task<IActionResult> ObterEmLote(
    [FromBody] IEnumerable<int> ids)
{ /* ... */ }

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "type": "https://api.empresa.com/errors/validacao",
  "title": "Erro de validação",
  "status": 422,
  "detail": "Um ou mais campos são inválidos.",
  "instance": "/api/pedidos",
  "errors": {
    "ClienteId": ["O ClienteId é obrigatório."],
    "Itens": ["A lista de itens não pode ser vazia."]
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

// Program.cs — habilita Problem Details (padrão no .NET 7+)
builder.Services.AddProblemDetails();

// Retornar problema diretamente
[HttpPost]
public IActionResult Criar([FromBody] CriarPedidoRequest req)
{
    if (req.ClienteId <= 0)
        return Problem(
            title: "ClienteId inválido",
            detail: "O ClienteId deve ser maior que zero.",
            statusCode: StatusCodes.Status422UnprocessableEntity,
            type: "https://api.empresa.com/errors/validacao");

    /* ... */
}

// Com ValidationProblemDetails para erros de ModelState:
if (!ModelState.IsValid)
    return ValidationProblem(ModelState); // retorna 400 + errors map padrão

1
2
3
4
5

[HttpPatch("{id:int}")]
public Task<IActionResult> Atualizar(
    [FromRoute] int id,
    [FromHeader(Name = "X-Idempotency-Key")] string? idempotencyKey,
    [FromBody] PedidoPatchRequest request)