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:
| RFC | Título | Relevancia para REST |
|---|---|---|
| RFC 3986 | Uniform Resource Identifier (URI) | Estructura y sintaxis de URLs |
| RFC 7230 | HTTP/1.1 Message Syntax | Sintaxis de requests y responses |
| RFC 7231 | HTTP/1.1 Semantics | Métodos, status codes, negociación de contenido |
| RFC 7232 | HTTP/1.1 Conditional Requests | ETags, If-None-Match (caché) |
| RFC 7234 | HTTP/1.1 Caching | Cache-Control, Expires |
| RFC 7235 | HTTP/1.1 Authentication | WWW-Authenticate, Authorization |
| RFC 5789 | PATCH Method for HTTP | Actualizaciones parciales de recursos |
| RFC 5988 | Web Linking | Header 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)
| |
Por qué está mal:
- El método HTTP ya lleva el verbo (
GET,POST,DELETE). Repetirget,create,deletaren la URL es redundante. - Usar
GETpara 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
| |
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/pedidosItensni/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 unPOST, cada intento puede crear un recurso nuevo. - Caché y prefetch: los navegadores precargan enlaces (
GET) precisamente porqueGETes 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.
| |
Idempotencia ≠ misma respuesta: un
DELETE /api/pedidos/42es idempotente porque el estado final (el pedido 42 no existe) es el mismo en todas las llamadas, aunque la segunda devuelva404en lugar de204. Lo que importa es el estado del servidor, no el código de retorno.
Propiedades esenciales de los métodos (RFC 7231)
| Método | Seguro¹ | Idempotente² | Cacheable³ | Body en la request | Body 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 encontrado404 Not Found— el recurso no existe304 Not Modified— la respuesta en caché no ha cambiado (con ETags)
| |
Atención:
GET /api/pedidos/buscarusa un sub-camino estático. Colócalo antes deGET /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+ headerLocation: /api/pedidos/42— recurso creado con éxito400 Bad Request— payload inválido409 Conflict— conflicto de unicidad (p. ej., e-mail duplicado)422 Unprocessable Entity— datos estructuralmente válidos pero semánticamente incorrectos
| |
POST también puede usarse para acciones que no encajan en un CRUD puro, como
/api/pedidos/42/cancelaro/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 actualizado204 No Content— recurso actualizado, sin cuerpo de respuesta404 Not Found— el recurso no existe400 / 422— payload inválido
| |
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. UnPUTsobre un recurso que aún no existe puede devolver201 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:
| |
2. JSON Patch (RFC 6902) — array de operaciones explícitas (add, remove, replace, move, copy, test):
| |
Implementándolo en ASP.NET Core:
| |
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 cuerpo200 OK— eliminado con éxito, devuelve una confirmación en el cuerpo404 Not Found— el recurso no existe409 Conflict— no se puede eliminar por dependencias (p. ej., pedido con ítems)
| |
Resumen de los Métodos en un Único Controller
Para visualizar cómo se articulan los métodos en un controller real:
| |
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#.
[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.
| |
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.
| |
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.
| |
[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>.
| |
[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.
| |
Para autenticación: prefiere siempre el header estándar
Authorization: Bearer <token>oAuthorization: Basic ...mediante[Authorize]de ASP.NET Core Identity / JWT, en lugar de headers personalizados.
Tabla Comparativa: Qué Atributo Usar y Cuándo
| Atributo | Fuente | Content-Type | Uso típico | ¿Sensible? |
|---|---|---|---|---|
[FromRoute] | Segmento /path/{id} | Cualquiera | Identificadores de recurso | ⚠️ Moderado |
[FromQuery] | Query string ?k=v | Cualquiera | Filtros, paginación, flags | ❌ No recomendado |
[FromBody] | Request body | application/json / application/xml | Creación, actualización completa | ✅ Preferible |
[FromForm] | Request body | multipart/form-data / url-encoded | Subida de archivos, formularios | ✅ Preferible |
[FromHeader] | HTTP Header | Cualquiera | Metadatos, 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:
| |
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
| Capa | Límite por defecto | ¿Configurable? | Observación |
|---|---|---|---|
| RFC 3986 | Sin límite definido | — | La especificación solo define la sintaxis |
| Internet Explorer 11 | 2.083 bytes | ❌ No | Límite histórico; IE descontinuado |
| Chrome / Edge / Firefox | ~32.000–65.000 bytes | ❌ No | En la práctica ilimitado para uso normal |
| Safari | ~80.000 bytes | ❌ No | |
| Apache HTTP Server | 8.190 bytes (LimitRequestLine) | ✅ Sí | Por defecto: 8 KB |
| Nginx | 8 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 Management | 4.096 bytes (4 KB) | ✅ Vía policy | Relevante para proxies |
| AWS ALB / CloudFront | 8.192 bytes | ✅ Sí | |
| CDNs en general | 2.048–8.192 bytes | Varía | Verificar 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.
| |
Configurando el límite en ASP.NET Core (Kestrel)
| |
Estrategias para evitar URLs largas
Problema: GET /api/pedidos?ids=1&ids=2&ids=3&...&ids=200 puede superar fácilmente los 2 KB.
| |
Status Codes: Convenciones REST
La semántica de HTTP solo funciona por completo cuando los status codes se usan correctamente:
| Rango | Significado | Ejemplos de uso REST |
|---|---|---|
| 2xx | Éxito | |
200 OK | Éxito general | GET, PUT, PATCH con retorno del recurso |
201 Created | Recurso creado | POST exitoso + header Location |
204 No Content | Éxito sin cuerpo | DELETE, PUT/PATCH sin retorno |
206 Partial Content | Contenido parcial | Descarga por rangos, streaming |
| 3xx | Redirección | |
301 Moved Permanently | La URL cambió definitivamente | Versionado de API |
304 Not Modified | Caché válida | GET con ETag/If-None-Match |
| 4xx | Error del cliente | |
400 Bad Request | Request malformada | Parámetros inválidos |
401 Unauthorized | No autenticado | Token ausente o inválido |
403 Forbidden | Autenticado, sin permiso | Acceso denegado al recurso |
404 Not Found | El recurso no existe | GET/PUT/DELETE de un ID inexistente |
405 Method Not Allowed | Método no soportado | DELETE en un recurso de solo lectura |
409 Conflict | Conflicto de estado | Unicidad violada, concurrencia |
410 Gone | Recurso eliminado permanentemente | Recursos con historial |
415 Unsupported Media Type | Content-Type no soportado | Body no JSON en un endpoint JSON |
422 Unprocessable Entity | Entidad semánticamente inválida | Falló la validación de negocio |
429 Too Many Requests | Rate limit alcanzado | Throttling de la API |
| 5xx | Error del servidor | |
500 Internal Server Error | Error no tratado | Excepción inesperada |
502 Bad Gateway | Error en el upstream | Proxy/gateway con backend fallando |
503 Service Unavailable | Servicio no disponible | Mantenimiento, 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:
| |
ASP.NET Core lo soporta de forma nativa:
| |
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:
| |
…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
- Full-Text Search en API REST: C#, SQL Server y PostgreSQL
- Arquitectura de Software: GoF, Patrones y Microservicios
- Paginación en APIs REST con C# y EF Core: Guía Práctica
- Cuello de Botella en Bases de Datos: Mensajería y Paginación
- Programación Asíncrona en C#: async/await y Threads
Referencias
- RFC 7231 — HTTP/1.1: Semantics and Content (IETF) — Definición oficial de los métodos HTTP y los status codes
- RFC 5789 — PATCH Method for HTTP (IETF) — Especificación formal del método PATCH
- RFC 3986 — Uniform Resource Identifier (URI) (IETF) — Sintaxis y estructura de URIs
- RFC 7807 — Problem Details for HTTP APIs (IETF) — Formato estándar para errores en APIs REST
- RFC 7396 — JSON Merge Patch (IETF) — Formato de PATCH mediante merge simple
- RFC 6902 — JSON Patch (IETF) — Formato de PATCH mediante operaciones explícitas
- Model Binding — Documentación oficial de ASP.NET Core — Referencia completa de
[FromRoute],[FromQuery],[FromBody],[FromForm],[FromHeader] - Repositorio blog-zocateli-sample — API Design — Código fuente completo de los ejemplos de este artículo
- Configure Kestrel — MaxRequestLineSize — Configuración de límites en el servidor Kestrel
- Problem Details — ASP.NET Core — Implementación de la RFC 7807 en ASP.NET Core

Al comentar, aceptas nuestra Política de Privacidad, Términos de Uso, Política de Eliminación de Datos.