Introducción

Construir una “API REST” y construir una API verdaderamente RESTful son cosas muy diferentes. La mayoría de los equipos entrega lo primero: URLs con verbos como /getPedidos, /createUsuario o /deletarProduto, métodos HTTP usados indistintamente y parámetros colocados donde resulta más conveniente — no donde tienen sentido semántico.

REST (Representational State Transfer) no es solo un estilo; es un conjunto de restricciones arquitectónicas formalizadas en RFCs. HTTP, el protocolo en el que se apoya REST, tiene su propia semántica definida en documentos como RFC 7231 (métodos y status codes), RFC 5789 (PATCH), RFC 3986 (URIs) y RFC 7230 (sintaxis de mensajes).

El punto central que muchos ignoran: el verbo de la acción ya está en el método HTTP. Colocarlo de nuevo en la URL es redundante, confuso y viola las restricciones REST.

En este artículo aprenderás a modelar recursos, no acciones; a usar cada método HTTP según la especificación; a entender los atributos de binding de ASP.NET Core ([FromRoute], [FromQuery], [FromBody], [FromForm], [FromHeader]) y cuándo aplica cada uno; y cuáles son los límites reales de longitud de URI que necesitas respetar.

Requisitos previos: C# básico, ASP.NET Core mínimo, familiaridad con HTTP.

📦 Código fuente: La implementación completa de este artículo está en el repositorio blog-zocateli-sample en GitHub. Clónalo, explóralo y adáptalo a tu contexto.


Las RFCs que Definen REST

REST fue propuesto por Roy Fielding en su tesis doctoral en 2000, pero la especificación técnica está en las RFCs del IETF. Conocer las principales evita reinventar la rueda y facilita la comunicación con otros desarrolladores:

RFCTítuloRelevancia para REST
RFC 3986Uniform Resource Identifier (URI)Estructura y sintaxis de URLs
RFC 7230HTTP/1.1 Message SyntaxSintaxis de requests y responses
RFC 7231HTTP/1.1 SemanticsMétodos, status codes, negociación de contenido
RFC 7232HTTP/1.1 Conditional RequestsETags, If-None-Match (caché)
RFC 7234HTTP/1.1 CachingCache-Control, Expires
RFC 7235HTTP/1.1 AuthenticationWWW-Authenticate, Authorization
RFC 5789PATCH Method for HTTPActualizaciones parciales de recursos
RFC 5988Web LinkingHeader Link, HATEOAS

Para el diseño del día a día, RFC 7231 y RFC 5789 son las que más impactan tus decisiones.


El Principio Fundamental: Recursos, No Acciones

El error más común en el diseño de APIs es modelar acciones/procedimientos en lugar de recursos. Compara:

❌ API RPC disfrazada de REST (verbos en la URL)

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

Por qué está mal:

  • El método HTTP ya lleva el verbo (GET, POST, DELETE). Repetir get, create, deletar en la URL es redundante.
  • Usar GET para eliminar (/deletarProduto) viola la semántica de seguridad de HTTP — los buscadores y el prefetch del navegador hacen GETs libremente.
  • No aprovecha el sistema de status codes de HTTP, lo que perjudica la interoperabilidad.
  • Dificulta el uso correcto de caché, idempotencia y middlewares.

✅ API REST con recursos

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
GET    /api/pedidos              → lista pedidos
POST   /api/pedidos              → crea un pedido
GET    /api/pedidos/{id}         → obtiene un pedido por id
PUT    /api/pedidos/{id}         → sustituye el pedido completo
PATCH  /api/pedidos/{id}         → actualiza parcialmente el pedido
DELETE /api/pedidos/{id}         → elimina un pedido

GET    /api/usuarios/{id}        → obtiene un usuario
GET    /api/usuarios/{id}/status → sub-recurso: estado del usuario

GET    /api/produtos?categoria=eletronicos  → filtro vía query string

La regla de oro: la URL identifica el recurso (el “qué”). El método HTTP indica la acción (el “cómo”). Nunca dupliques el método HTTP como verbo en la URL.

Convenciones de nomenclatura

  • Usa sustantivos en plural para colecciones: /pedidos, /usuarios, /produtos
  • Usa plural incluso para un recurso individual: /pedidos/{id} (no /pedido/{id})
  • Usa kebab-case: /pedidos-itens (no /pedidosItens ni /pedidos_itens)
  • Los sub-recursos expresan relaciones: /pedidos/{id}/itens, /usuarios/{id}/enderecos
  • Evita jerarquías profundas (más de 2 niveles); prefiere query strings: GET /itens?pedidoId=42

Los Métodos HTTP en Detalle

Antes de analizar cada método individualmente, dos conceptos de la RFC 7231 deben quedar claros: seguridad e idempotencia. Definen cómo clientes, proxies y navegadores pueden comportarse con cada método — e ignorarlos provoca bugs sutiles y difíciles de rastrear.

¿Qué es la Idempotencia?

La idempotencia es la propiedad de una operación que, al ejecutarse múltiples veces, produce exactamente el mismo resultado que si se hubiera ejecutado una sola vez. El término viene de las matemáticas (operadores idempotentes como |x| o x * 1), pero en HTTP su significado es práctico: el estado final del servidor debe ser idéntico, sin importar cuántas veces se envíe la request.

Analogía: pulsar el botón de cerrar la puerta de un ascensor una vez o diez veces tiene el mismo efecto — la puerta se cierra. Eso es idempotente. Pulsar el botón de un piso tiene efecto en cada toque — no es idempotente.

¿Por qué importa esto en la práctica?

  • Retry automático: clientes y proxies pueden reenviar requests idempotentes tras un fallo de red sin riesgo de efectos secundarios duplicados. Con un PUT, puedes intentarlo de nuevo con seguridad. Con un POST, cada intento puede crear un recurso nuevo.
  • Caché y prefetch: los navegadores precargan enlaces (GET) precisamente porque GET es seguro e idempotente — la operación no cambia nada en el servidor.
  • Circuit breakers y políticas de retry: bibliotecas como Polly configuran el retry automático por defecto solo para métodos idempotentes.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
// ✅ PUT es idempotente: enviarlo 3 veces tiene el mismo efecto que enviarlo 1 vez
// El pedido 42 termina con status "cancelado" en todos los casos
PUT /api/pedidos/42  →  { "status": "cancelado" }
PUT /api/pedidos/42  →  { "status": "cancelado" }  // mismo resultado
PUT /api/pedidos/42  →  { "status": "cancelado" }  // mismo resultado

// ❌ POST NO es idempotente: cada llamada crea un nuevo pedido
POST /api/pedidos  →  { "id": 100, ... }
POST /api/pedidos  →  { "id": 101, ... }  // recurso DIFERENTE creado
POST /api/pedidos  →  { "id": 102, ... }  // recurso DIFERENTE creado

// ⚠️ PATCH puede o no ser idempotente — depende de la semántica:
PATCH /api/pedidos/42  →  { "status": "processando" }  // ✅ idempotente
PATCH /api/pedidos/42  →  { "tentativas": "+1" }        // ❌ no idempotente

Idempotencia ≠ misma respuesta: un DELETE /api/pedidos/42 es idempotente porque el estado final (el pedido 42 no existe) es el mismo en todas las llamadas, aunque la segunda devuelva 404 en lugar de 204. Lo que importa es el estado del servidor, no el código de retorno.


Propiedades esenciales de los métodos (RFC 7231)

MétodoSeguro¹Idempotente²Cacheable³Body en la requestBody en la response
GET✅✅✅❌ No✅ Sí
HEAD✅✅✅❌ No❌ No (solo headers)
POST❌❌⚠️ Raramente✅ Sí✅ Sí
PUT❌✅❌✅ Sí✅ Opcional
PATCH❌⚠️ Depende❌✅ Sí✅ Opcional
DELETE❌✅❌⚠️ Raramente✅ Opcional
OPTIONS✅✅❌❌✅ Sí

¹ Seguro: no causa efectos secundarios en el servidor; los navegadores pueden llamarlo sin pedir confirmación.
² Idempotente: llamarlo N veces tiene el mismo efecto que llamarlo una vez.
³ Cacheable: la respuesta puede ser almacenada en caché por proxies y navegadores.


GET — Lectura de Recursos

GET es seguro e idempotente: nunca debe modificar el estado en el servidor. Devuelve una representación del recurso.

Status codes esperados:

  • 200 OK — recurso encontrado
  • 404 Not Found — el recurso no existe
  • 304 Not Modified — la respuesta en caché no ha cambiado (con ETags)
 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 libre
    [HttpGet("buscar")]
    [ProducesResponseType<IEnumerable<PedidoDto>>(StatusCodes.Status200OK)]
    public async Task<IActionResult> Buscar(
        [FromQuery] string termo,
        CancellationToken ct = default)
    {
        if (string.IsNullOrWhiteSpace(termo))
            return BadRequest("El parámetro 'termo' es obligatorio.");

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

Atención: GET /api/pedidos/buscar usa un sub-camino estático. Colócalo antes de GET /api/pedidos/{id} o usa constraints de ruta ({id:int}) para evitar conflictos.


POST — Creación de Recursos

POST no es idempotente: dos llamadas idénticas pueden crear dos recursos distintos. Es el método correcto para crear un nuevo recurso en una colección. El servidor determina la identidad del nuevo recurso.

Status codes esperados:

  • 201 Created + header Location: /api/pedidos/42 — recurso creado con éxito
  • 400 Bad Request — payload inválido
  • 409 Conflict — conflicto de unicidad (p. ej., e-mail duplicado)
  • 422 Unprocessable Entity — datos estructuralmente válidos pero semánticamente incorrectos
 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 + header Location es el estándar REST para la creación
    return CreatedAtAction(nameof(ObterPorId), new { id = pedido.Id }, pedido);
}

/// POST /api/pedidos/42/itens — añade un ítem al 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);
}

POST también puede usarse para acciones que no encajan en un CRUD puro, como /api/pedidos/42/cancelar o /api/pagamentos/processar. En estas situaciones, úsalo con moderación y documéntalo bien — es una excepción tolerada, no la regla.


PUT — Sustitución Completa del Recurso

PUT es idempotente: enviar la misma request N veces tiene el mismo resultado que enviarla una vez. Sustituye el recurso entero — si omites un campo, se borrará (o volverá a su valor por defecto). Nunca uses PUT para actualizaciones parciales.

Status codes esperados:

  • 200 OK — recurso actualizado, devuelve el recurso actualizado
  • 204 No Content — recurso actualizado, sin cuerpo de respuesta
  • 404 Not Found — el recurso no existe
  • 400 / 422 — payload inválido
 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 los campos deben 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("El id de la URL no corresponde al id del payload.");

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

/// PUT /api/usuarios/10 — sustitución completa del usuario
[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();
}

PUT vs POST para creación: Algunos diseños permiten PUT /api/pedidos/{id} para crear un recurso con ID predefinido (upsert). Es válido según la RFC 7231, pero debe documentarse explícitamente. Un PUT sobre un recurso que aún no existe puede devolver 201 Created.


PATCH — Actualización Parcial (RFC 5789)

PATCH se formalizó en la RFC 5789 precisamente porque PUT es inadecuado para actualizaciones parciales. Con PATCH, envías solo los campos que quieres modificar; los demás permanecen intactos.

PATCH no es idempotente de forma garantizada — depende de la implementación. Un PATCH { "views": "+1" } no es idempotente; un PATCH { "status": "ativo" } sí lo es.

Dos formatos comunes de payload:

1. Merge Patch (RFC 7396) — más simple, envía solo el delta como JSON normal:

1
2
3
4
PATCH /api/pedidos/42
Content-Type: application/merge-patch+json

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

2. JSON Patch (RFC 6902) — array de operaciones explícitas (add, remove, replace, move, copy, test):

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" }
]

Implementándolo en ASP.NET Core:

 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 — necesario para JSON Patch
builder.Services.AddControllersWithViews()
    .AddNewtonsoftJson(); // JSON Patch requiere Newtonsoft.Json

/// PATCH /api/pedidos/42 — Merge Patch (enfoque simple y recomendado)
[HttpPatch("{id:int}")]
[ProducesResponseType<PedidoDto>(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<IActionResult> AtualizarParcial(
    [FromRoute] int id,
    [FromBody] AtualizarPedidoRequest request,  // Solo campos anulables
    CancellationToken ct = default)
{
    var atualizado = await _service.AtualizarParcialAsync(id, request, ct);
    return atualizado is null ? NotFound() : Ok(atualizado);
}

// DTO para Merge Patch: campos nulos = no modificar
public record AtualizarPedidoRequest(
    string? Status,                 // null = no cambia
    string? MotivoCancelamento,     // null = no cambia
    decimal? Desconto               // null = no cambia
);

// En el service: actualiza solo los campos con 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();
}

DELETE — Eliminación de Recursos

DELETE es idempotente: eliminar un recurso que ya no existe debe devolver 404 (o 204 / 200 en diseños más tolerantes), pero nunca 500.

Status codes esperados:

  • 204 No Content — eliminado con éxito, sin cuerpo
  • 200 OK — eliminado con éxito, devuelve una confirmación en el cuerpo
  • 404 Not Found — el recurso no existe
  • 409 Conflict — no se puede eliminar por dependencias (p. ej., pedido con ítems)
 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 = "El pedido tiene ítems vinculados." }),
        _ => NoContent()
    };
}

/// DELETE /api/pedidos/42/itens/7 — eliminación 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 en lote (úsalo con 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 }

Resumen de los Métodos en un Único Controller

Para visualizar cómo se articulan los métodos en un controller real:

 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}    ← sustituye el producto ENTERO
    [HttpPut("{id:guid}")]
    public async Task<IActionResult> Substituir([FromRoute] Guid id, [FromBody] ProdutoRequest req) { /* ... */ return Ok(); }

    // PATCH /api/produtos/{id}  ← actualiza SOLO los 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(); }
}

Parameter Binding: De Dónde Vienen los Datos en ASP.NET Core

ASP.NET Core necesita saber de dónde extraer cada parámetro de una action. Esto se hace mediante atributos de binding que mapean partes de la request HTTP a parámetros de C#.

Diagrama de los atributos de binding en ASP.NET Core: FromRoute, FromQuery, FromBody, FromForm, FromHeader


[FromRoute] — Parámetro en la URL (path segment)

Extrae valores de segmentos de ruta definidos en la plantilla con {nombre}.

Cuándo usarlo: identificadores de recurso en la URL — IDs, slugs, versiones, locales.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
// Ruta: GET /api/pedidos/{id}/itens/{itemId}
[HttpGet("{id:int}/itens/{itemId:int}")]
public async Task<IActionResult> ObterItem(
    [FromRoute] int id,       // extrae de {id}
    [FromRoute] int itemId)   // extrae de {itemId}
{ /* ... */ }

// Ruta: 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 en la ruta: :int, :guid, :long, :alpha, :regex(...)
[HttpGet("{id:guid}")]
// [FromRoute] se INFIERE para parámetros que coinciden con segmentos de ruta
public async Task<IActionResult> ObterPorGuid(Guid id)
{ /* ... */ }  // inferencia automática: funciona sin [FromRoute]

Las constraints de ruta ({id:int}, {id:guid}, {id:min(1)}) evitan que las rutas “se filtren” hacia actions equivocadas antes de llegar al action method.


[FromQuery] — Parámetro en la Query String

Extrae valores de la query string (?clave=valor&otraClave=valor2). Ideal para filtros, ordenación, paginación y parámetros opcionales.

Cuándo usarlo: filtrado, búsqueda, ordenación, paginación, flags opcionales.

 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 en la query string: GET /api/produtos?ids=1&ids=2&ids=3
// o con separador: GET /api/produtos?ids=1,2,3
[HttpGet("batch")]
public async Task<IActionResult> ObterEmLote(
    [FromQuery] int[] ids)    // ASP.NET Core resuelve ambos formatos
{ /* ... */ }

// DTO para la query string — útil cuando hay muchos 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
);

// Nombre de parámetro distinto del campo C# mediante [FromQuery(Name = "...")]
[HttpGet("relatorio")]
public async Task<IActionResult> Relatorio(
    [FromQuery(Name = "data_inicio")] DateOnly dataInicio,
    [FromQuery(Name = "data_fim")]    DateOnly dataFim)
{ /* ... */ }

Nunca uses [FromQuery] para datos sensibles (contraseñas, tokens). Las query strings aparecen en los logs del servidor, en el historial del navegador y en los headers Referer.


[FromBody] — Parámetro en el Cuerpo de la Request

Extrae el cuerpo de la request (generalmente JSON, pero puede ser XML u otro content type) y lo deserializa al tipo de C#. Solo un parámetro por action puede tener [FromBody].

Cuándo usarlo: creación (POST), sustitución (PUT), actualización parcial (PATCH), eliminación en lote mediante payload.

 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 — crea un pedido
// Header: Content-Type: application/json
[HttpPost]
public async Task<IActionResult> Criar(
    [FromBody] CriarPedidoRequest request)   // deserializa JSON → C#
{ /* ... */ }

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

// ASP.NET Core con System.Text.Json (por defecto) + propiedades obligatorias
public record CriarItemPedidoRequest(
    [Required] int ProdutoId,
    [Required, Range(1, 9999)] int Quantidade,
    decimal? DescontoUnitario
);

// Validación automática con [ApiController]:
// Si ModelState es inválido, devuelve 400 Bad Request automáticamente
// Sin necesidad de verificar ModelState manualmente

// Configuración global del serializer:
builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        options.JsonSerializerOptions.PropertyNamingPolicy =
            JsonNamingPolicy.CamelCase;         // clienteId, no ClienteId
        options.JsonSerializerOptions.DefaultIgnoreCondition =
            JsonIgnoreCondition.WhenWritingNull; // omite null en el output
        options.JsonSerializerOptions.Converters.Add(
            new JsonStringEnumConverter());      // enum como string
    });

[FromBody] con tipos primitivos funciona, pero es raro y genera confusión. Para un único valor simple, prefiere [FromQuery] o [FromRoute]. El body es adecuado para objetos estructurados.


[FromForm] — Parámetro mediante Formulario HTML

Extrae datos de requests con Content-Type: multipart/form-data o application/x-www-form-urlencoded. Indispensable para la subida de archivos (IFormFile).

Cuándo usarlo: subida de archivos, formularios HTML tradicionales, APIs consumidas directamente por un <form>.

 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 — subida de imagen con metadatos
// 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,         // archivo
    [FromForm] string? altText,          // campo de texto del form
    [FromForm] bool isPrincipal = false, // flag booleano del form
    CancellationToken ct = default)
{
    if (imagem.Length == 0)
        return BadRequest("Archivo vacío.");

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

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

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

// Subida de múltiples archivos
[HttpPost("importar")]
[Consumes("multipart/form-data")]
public async Task<IActionResult> Importar(
    [FromForm] IFormFileCollection arquivos,  // colección de archivos
    [FromForm] string tipo,
    CancellationToken ct = default)
{ /* ... */ }

// DTO para un formulario complejo
[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 archivo opcional
);

[FromBody] y [FromForm] son mutuamente excluyentes en una misma action — ambos leen el body de la request. Nunca combines los dos en la misma action.


[FromHeader] — Parámetro en un Header HTTP

Extrae valores de los headers de la request. Útil para metadatos de transacción, correlación, versión de la API o campos de autenticación personalizados.

Cuándo usarlo: correlation ID, tenant ID, versión del cliente, API key personalizada, campos que no son datos del recurso.

 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 — con headers de correlación y 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 el correlation ID para logging y trazabilidad distribuida
    using var _ = _logger.BeginScope(new { correlationId, tenantId });
    return Ok(await _service.ListarAsync(tenantId, pagina, ct));
}

// API con la versión en el header (alternativa al versionado por URL)
// Header: X-Api-Version: 2
[HttpGet("~/api/relatorios")]
public async Task<IActionResult> Relatorio(
    [FromHeader(Name = "X-Api-Version")] int versao = 1)
{ /* ... */ }

// Ejemplo con API key personalizada (prefiere siempre Authorization estándar)
[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 (pagos, operaciones 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);  // respuesta idempotente
    }
    /* procesa el pago... */
}

Para autenticación: prefiere siempre el header estándar Authorization: Bearer <token> o Authorization: Basic ... mediante [Authorize] de ASP.NET Core Identity / JWT, en lugar de headers personalizados.


Tabla Comparativa: Qué Atributo Usar y Cuándo

AtributoFuenteContent-TypeUso típico¿Sensible?
[FromRoute]Segmento /path/{id}CualquieraIdentificadores de recurso⚠️ Moderado
[FromQuery]Query string ?k=vCualquieraFiltros, paginación, flags❌ No recomendado
[FromBody]Request bodyapplication/json / application/xmlCreación, actualización completa✅ Preferible
[FromForm]Request bodymultipart/form-data / url-encodedSubida de archivos, formularios✅ Preferible
[FromHeader]HTTP HeaderCualquieraMetadatos, correlación, tenant✅ Preferible

Regla práctica:

  • El recurso va en la ruta: [FromRoute]
  • Filtros y opciones van en la query string: [FromQuery]
  • Datos estructurados (el payload) van en el body: [FromBody]
  • Archivos y formularios HTML van en el form: [FromForm]
  • Metadatos de transporte y contexto van en el header: [FromHeader]

Inferencia automática (sin atributo)

En ASP.NET Core con [ApiController], el binding se infiere automáticamente:

 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 infiere automáticamente:
    // - Guid id → [FromRoute] (coincide con {id} en la ruta)
    // - Request request → [FromBody] (tipo complejo = body por defecto con [ApiController])
    [HttpPut("{id:guid}")]
    public IActionResult Atualizar(Guid id, ProdutoRequest request)
    { /* ... */ return Ok(); }

    // string categoria → [FromQuery] (tipo simple que no está en la ruta = query string)
    [HttpGet]
    public IActionResult Listar(string? categoria, int pagina = 1)
    { /* ... */ return Ok(); }
}

La inferencia funciona bien para casos simples, pero ser explícito con los atributos mejora la legibilidad y evita sorpresas cuando cambian las plantillas de ruta.


Límites de Longitud de URL / URI

Esta es una de las cuestiones más prácticas y más ignoradas. La especificación RFC 3986 no define un límite máximo para las URIs, pero todos los clientes y servidores implementan sus propios límites — y varían bastante.

Límites por capa

CapaLímite por defecto¿Configurable?Observación
RFC 3986Sin límite definido—La especificación solo define la sintaxis
Internet Explorer 112.083 bytes❌ NoLímite histórico; IE descontinuado
Chrome / Edge / Firefox~32.000–65.000 bytes❌ NoEn la práctica ilimitado para uso normal
Safari~80.000 bytes❌ No
Apache HTTP Server8.190 bytes (LimitRequestLine)✅ SíPor defecto: 8 KB
Nginx8 KB (large_client_header_buffers)✅ SíBuffer de headers incluido
IIS (Kestrel)16.384 bytes (16 KB)✅ SíIncluye línea de request + headers
ASP.NET Core (Kestrel)8.192 bytes✅ SíMaxRequestLineSize
Azure API Management4.096 bytes (4 KB)✅ Vía policyRelevante para proxies
AWS ALB / CloudFront8.192 bytes✅ Sí
CDNs en general2.048–8.192 bytesVaríaVerificar por producto

El límite seguro en la práctica

Usa como máximo 2.000 bytes (2 KB) para URLs si quieres compatibilidad universal. Para APIs internas sin IE ni CDNs antiguas, 8 KB es razonable.

La URL se compone de: esquema + host + ruta + query string + fragment. Lo que crece más rápido es la query string — especialmente al pasar listas de IDs, filtros combinados o datos en Base64.

1
2
3
4
https://api.empresa.com/api/produtos/pesquisar
?ids=1,2,3,4,5,...,200          ← ⚠️ puede superar el límite
&filtros={"categoria":"...", "tags":["a","b",...]}  ← ❌ nunca hagas esto
&token=eyJhbGciOiJSUzI1NiIsInR5cCI6...  ← ❌ nunca pongas un token en la URL

Configurando el límite en ASP.NET Core (Kestrel)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
// Program.cs — ajusta el límite de la línea de request
builder.WebHost.ConfigureKestrel(options =>
{
    options.Limits.MaxRequestLineSize = 16_384;    // 16 KB (por defecto: 8 KB)
    options.Limits.MaxRequestHeadersTotalSize = 32_768; // 32 KB para headers
    options.Limits.MaxRequestBodySize = 10 * 1024 * 1024; // 10 MB para el body
});

// Para un endpoint específico con un límite mayor:
app.MapPost("/api/importar", ImportarHandler)
   .WithMetadata(new RequestSizeLimitAttribute(50 * 1024 * 1024)); // 50 MB

Estrategias para evitar URLs largas

Problema: GET /api/pedidos?ids=1&ids=2&ids=3&...&ids=200 puede superar fácilmente los 2 KB.

 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 con muchos IDs en la query string
// GET /api/pedidos?ids=1&ids=2&ids=3... (puede superar el límite)

// ✅ Solución 1: POST para búsquedas complejas (pragmático, no REST puro)
// 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
);

// ✅ Solución 2: Cursor token codificado en Base64 (para paginación)
// GET /api/pedidos?cursor=eyJpZCI6MTAwLCJkYXRhIjoiMjAyNi0wMS0wMSJ9
// El cursor lleva los criterios de búsqueda serializados y de forma opaca
[HttpGet]
public async Task<IActionResult> ListarComCursor(
    [FromQuery] string? cursor,
    [FromQuery] int limite = 20)
{ /* deserializa el cursor, aplica el filtro... */ }

// ✅ Solución 3: Endpoint de lote con body explícito
// POST /api/produtos/lote — busca productos por una lista de IDs en el body
[HttpPost("lote")]
public async Task<IActionResult> ObterEmLote(
    [FromBody] IEnumerable<int> ids)
{ /* ... */ }

Status Codes: Convenciones REST

La semántica de HTTP solo funciona por completo cuando los status codes se usan correctamente:

RangoSignificadoEjemplos de uso REST
2xxÉxito
200 OKÉxito generalGET, PUT, PATCH con retorno del recurso
201 CreatedRecurso creadoPOST exitoso + header Location
204 No ContentÉxito sin cuerpoDELETE, PUT/PATCH sin retorno
206 Partial ContentContenido parcialDescarga por rangos, streaming
3xxRedirección
301 Moved PermanentlyLa URL cambió definitivamenteVersionado de API
304 Not ModifiedCaché válidaGET con ETag/If-None-Match
4xxError del cliente
400 Bad RequestRequest malformadaParámetros inválidos
401 UnauthorizedNo autenticadoToken ausente o inválido
403 ForbiddenAutenticado, sin permisoAcceso denegado al recurso
404 Not FoundEl recurso no existeGET/PUT/DELETE de un ID inexistente
405 Method Not AllowedMétodo no soportadoDELETE en un recurso de solo lectura
409 ConflictConflicto de estadoUnicidad violada, concurrencia
410 GoneRecurso eliminado permanentementeRecursos con historial
415 Unsupported Media TypeContent-Type no soportadoBody no JSON en un endpoint JSON
422 Unprocessable EntityEntidad semánticamente inválidaFalló la validación de negocio
429 Too Many RequestsRate limit alcanzadoThrottling de la API
5xxError del servidor
500 Internal Server ErrorError no tratadoExcepción inesperada
502 Bad GatewayError en el upstreamProxy/gateway con backend fallando
503 Service UnavailableServicio no disponibleMantenimiento, sobrecarga

Problem Details: Respuestas de Error Estandarizadas (RFC 7807)

Además de los status codes, la RFC 7807 define un formato estándar para errores en APIs HTTP — application/problem+json:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "type": "https://api.empresa.com/errors/validacao",
  "title": "Error de validación",
  "status": 422,
  "detail": "Uno o más campos son inválidos.",
  "instance": "/api/pedidos",
  "errors": {
    "ClienteId": ["El ClienteId es obligatorio."],
    "Itens": ["La lista de ítems no puede estar vacía."]
  }
}

ASP.NET Core lo soporta de forma nativa:

 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 (por defecto en .NET 7+)
builder.Services.AddProblemDetails();

// Devolver un problema directamente
[HttpPost]
public IActionResult Criar([FromBody] CriarPedidoRequest req)
{
    if (req.ClienteId <= 0)
        return Problem(
            title: "ClienteId inválido",
            detail: "El ClienteId debe ser mayor que cero.",
            statusCode: StatusCodes.Status422UnprocessableEntity,
            type: "https://api.empresa.com/errors/validacao");

    /* ... */
}

// Con ValidationProblemDetails para errores de ModelState:
if (!ModelState.IsValid)
    return ValidationProblem(ModelState); // devuelve 400 + errors map estándar

Checklist de Diseño REST

Antes de publicar un endpoint, verifica:

  • ¿La URL identifica un recurso (sustantivo) y no una acción (verbo)?
  • ¿El método HTTP (GET, POST, PUT, PATCH, DELETE) expresa la acción correcta?
  • ¿Los datos de identificación están en la ruta ([FromRoute])?
  • ¿Los filtros y la paginación están en la query string ([FromQuery])?
  • ¿El payload estructurado está en el body ([FromBody])?
  • ¿Los archivos se envían mediante form ([FromForm])?
  • ¿Los metadatos de transporte están en headers ([FromHeader])?
  • ¿La URL tiene menos de 2.000 bytes?
  • ¿El status code de éxito es el correcto (200, 201, 204)?
  • ¿Los errores devuelven Problem Details (RFC 7807)?
  • ¿Las acciones de creación devuelven el header Location?
  • ¿PUT recibe el recurso completo (no parcial)?
  • ¿Los datos sensibles nunca están en la URL o en la query string?

Conclusión

REST no es una tecnología — es una disciplina de diseño. La diferencia entre una API REST y una API RPC servida vía HTTP está precisamente en respetar la semántica del protocolo: URLs que identifican recursos, métodos que expresan acciones, status codes que comunican resultados y parámetros que llegan por el canal semánticamente correcto.

Los atributos [FromRoute], [FromQuery], [FromBody], [FromForm] y [FromHeader] en ASP.NET Core no son solo comodidades sintácticas — documentan y hacen cumplir las intenciones de diseño. Una signature como:

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)

…se explica por sí sola: qué identifica el recurso, qué es metadato de transporte y qué es el payload de datos.

Y sobre los límites de URL: respeta los 2 KB para compatibilidad universal. Si tu query string crece más allá de eso, es una señal de que el dato pertenece al body o de que el diseño necesita revisarse.


Lee También


Referencias