API RESTful

Fundamentos Security Notes Jan 9, 2026 JAVASCRIPT
arquitectura rest diseño-api http buenas-practicas

Definición

Una API RESTful es un servicio web que implementa completamente el estilo arquitectónico REST (Transferencia de Estado Representacional). Aunque muchas APIs afirman ser “APIs REST”, una API verdaderamente RESTful se adhiere a las seis restricciones de REST: separación cliente-servidor, sin estado, cacheabilidad, sistema en capas, interfaz uniforme y, opcionalmente, código bajo demanda.

La diferencia clave entre una “API REST” y una “API RESTful” es la completitud. Muchas APIs usan HTTP y JSON y se llaman REST, pero pueden violar el principio de ausencia de estado al mantener sesiones del lado del servidor, o pueden ignorar HATEOAS (hipermedia como motor del estado de la aplicación). Una API RESTful sigue todos los principios rigurosamente, haciéndola verdaderamente escalable, mantenible y autodescriptiva.

El Modelo de Madurez de Richardson se usa a menudo para medir cuán RESTful es una API, con niveles del 0 (el pantano de POX - Plain Old XML) al 3 (la gloria de REST con controles de hipermedia completos). Una API genuinamente RESTful alcanza el nivel 3.

Ejemplo

API de GitHub v3: La API REST de GitHub es un ejemplo bien conocido de una API RESTful. Usa recursos (/repos, /users, /issues), métodos HTTP apropiados (GET para leer, POST para crear, PATCH para actualizar, DELETE para eliminar), incluye enlaces de hipermedia en las respuestas (URLs de navegación), implementa caché con ETags, y mantiene la ausencia de estado - cada solicitud contiene toda la información necesaria.

API de Stripe: La API de pagos de Stripe es altamente RESTful. Crear un cargo es POST /v1/charges, recuperarlo es GET /v1/charges/:id, y reembolsarlo es POST /v1/refunds. Las respuestas incluyen enlaces de hipermedia como "url": "/v1/charges/ch_xxx" para recursos relacionados. Es sin estado, usa claves de idempotencia para reintentos seguros y aprovecha correctamente los códigos de estado HTTP.

API de Twilio: Cuando envías un SMS vía Twilio, haces POST a /2010-04-01/Accounts/{AccountSid}/Messages.json. La respuesta incluye URLs a recursos relacionados como adjuntos multimedia y registros de mensajes. Cada solicitud incluye credenciales de autenticación (sin estado), y las respuestas usan códigos de estado HTTP apropiados (201 para creado, 400 para solicitud incorrecta).

API de Administración de Shopify: La API de Shopify para gestionar tiendas es RESTful: GET /admin/api/2024-01/products.json lista productos, POST /admin/api/2024-01/products.json crea uno, PUT /admin/api/2024-01/products/{id}.json lo actualiza. Las respuestas incluyen enlaces de paginación y relaciones de recursos, haciendo la API autonavegable.

Analogía

El Restaurante de Autoservicio: Una API RESTful es como un restaurante de autoservicio bien diseñado. El menú (documentación de la API) te dice qué está disponible. Cada mostrador es un recurso (barra de ensaladas, parrilla, bebidas). No necesitas recordar qué pediste antes (sin estado) - solo vas al mostrador y obtienes lo que quieres. Cada mostrador tiene señales claras (interfaz uniforme) que te dicen cómo interactuar con él. La caja (respuesta) te da un recibo con códigos QR enlazando a información nutricional y advertencias de alérgenos (enlaces de hipermedia) para que puedas descubrir información relacionada sin preguntar.

La Biblioteca con Señalización Perfecta: Una API RESTful es como una biblioteca donde cada libro tiene un código de barras único (identificador de recurso), cada sección tiene señales claras (interfaz uniforme), y las tarjetas de préstamo incluyen recomendaciones “si te gustó esto, ver también” (hipermedia). No necesitas un bibliotecario que te guíe de la mano - el sistema es autodescriptivo. Ya sea que visitaras ayer o nunca antes (sin estado), puedes navegarlo fácilmente.

El Sistema de Autopistas: Piensa en una API RESTful como un sistema de autopistas moderno. Cada salida tiene un número único (ID de recurso), las señales están estandarizadas en todo el país (interfaz uniforme), no necesitas registrarte con la autoridad de autopistas para cada viaje (sin estado), y cada salida tiene señales apuntando a destinos relacionados (hipermedia). Puedes entrar al sistema desde cualquier lugar y navegar usando solo las señales.

Ejemplo de Código

// Una respuesta de API genuinamente RESTful incluye enlaces de hipermedia
// Ejemplo: respuesta de repositorio estilo GitHub

// GET /api/repos/facebook/react
{
  "id": 10270250,
  "name": "react",
  "full_name": "facebook/react",
  "description": "A JavaScript library for building user interfaces",
  "url": "https://api.github.com/repos/facebook/react",
  "html_url": "https://github.com/facebook/react",

  // Enlaces de hipermedia (HATEOAS) - navegación descubrible
  "forks_url": "https://api.github.com/repos/facebook/react/forks",
  "keys_url": "https://api.github.com/repos/facebook/react/keys{/key_id}",
  "collaborators_url": "https://api.github.com/repos/facebook/react/collaborators{/collaborator}",
  "issues_url": "https://api.github.com/repos/facebook/react/issues{/number}",
  "pulls_url": "https://api.github.com/repos/facebook/react/pulls{/number}",
  "milestones_url": "https://api.github.com/repos/facebook/react/milestones{/number}",

  // El estado está representado, no almacenado del lado del servidor
  "stargazers_count": 212000,
  "watchers_count": 212000,
  "language": "JavaScript",
  "has_issues": true,
  "has_projects": true,

  // Control de caché para escalabilidad
  "updated_at": "2026-01-09T10:30:00Z"
}

// Las cabeceras de respuesta demuestran principios RESTful
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=60, s-maxage=60
ETag: "686897696a7c876b7e"
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
Link: <https://api.github.com/repos/facebook/react/commits>; rel="commits"

// Solicitud subsecuente con caché (sin estado)
GET /api/repos/facebook/react
If-None-Match: "686897696a7c876b7e"

// El servidor responde con 304 Not Modified si no ha cambiado
HTTP/1.1 304 Not Modified
Cache-Control: max-age=60

Diagrama

graph TB
    subgraph "RESTful API Constraints"
        CS[Client-Server
Separation]
        SL[Stateless
Communication]
        CA[Cacheable
Responses]
        LS[Layered
System]
        UI[Uniform
Interface]
        COD[Code-on-Demand
(Optional)]
    end

    subgraph "Uniform Interface Constraints"
        RI[Resource
Identification]
        RM[Resource Manipulation
via Representations]
        SM[Self-Descriptive
Messages]
        HM[Hypermedia as
Engine of State]
    end

    UI --> RI
    UI --> RM
    UI --> SM
    UI --> HM

    subgraph "Richardson Maturity Model"
        L0[Level 0
The Swamp of POX]
        L1[Level 1
Resources]
        L2[Level 2
HTTP Verbs]
        L3[Level 3
Hypermedia Controls]

        L0 -->|Introduce Resources| L1
        L1 -->|HTTP Methods + Status Codes| L2
        L2 -->|HATEOAS| L3
    end

    L3 -.->|Fully RESTful| CS

Notas de Seguridad

SECURITY NOTES

Requisitos Principales:

  • Las APIs RESTful deben implementar autenticación en cada solicitud debido a la ausencia de estado (sin sesiones del lado del servidor).
  • Usa OAuth 2.0 o JWT con validación de firma adecuada.
  • Implementa limitación de tasa por cliente para prevenir abusos.
  • Usa HTTPS exclusivamente para proteger credenciales y datos en tránsito.
  • Valida todos los datos de entrada y sanitiza las salidas para prevenir ataques de inyección.
  • Implementa políticas CORS apropiadas.

Mejores Prácticas:

  • Usa cabeceras Content-Security-Policy.
  • Aprovecha las cabeceras de caché cuidadosamente para evitar exponer datos sensibles en cachés compartidas.
  • Implementa claves de idempotencia para operaciones inseguras para prevenir procesamiento duplicado.
  • Sigue el principio de menor privilegio en la autorización.
  • Nunca expongas IDs de recursos internos que podrían filtrar lógica de negocio.
  • Usa versionado de API para mantener parches de seguridad sin cambios que rompan compatibilidad..

Mejores Prácticas

  1. Alcanza el Nivel 3 de Richardson: Implementa hipermedia completa con enlaces en las respuestas
  2. Diseña URLs orientadas a recursos: Usa sustantivos (/users/123/orders) no verbos (/getUserOrders?id=123)
  3. Usa métodos HTTP correctamente: GET para leer, POST para crear, PUT/PATCH para actualizar, DELETE para eliminar
  4. Retorna códigos de estado apropiados: 200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error
  5. Implementa caché: Usa cabeceras ETags, Last-Modified, Cache-Control para reducir la carga
  6. Soporta negociación de contenido: Acepta múltiples formatos vía cabecera Accept (JSON, XML, etc.)
  7. Incluye paginación para colecciones: Usa limit, offset, o paginación basada en cursor con enlaces a next, prev
  8. Versiona tu API: Usa versionado por URI (/v1/) o versionado por cabecera Accept
  9. Proporciona documentación completa: Usa OpenAPI/Swagger para describir tu API
  10. Implementa HATEOAS: Incluye enlaces de navegación para que los clientes puedan descubrir recursos dinámicamente

Errores Comunes

Sesiones con estado: Almacenar estado del usuario en el servidor viola la ausencia de estado. Usa tokens (JWT, OAuth) que llevan todo el contexto necesario.

Falta de hipermedia: Retornar datos sin enlaces hace la API menos descubrible. Los clientes no deberían necesitar construir URLs manualmente.

Métodos HTTP incorrectos: Usar GET para operaciones que modifican estado, o POST para todo, rompe la interfaz uniforme.

Códigos de estado pobres: Retornar 200 OK para todas las respuestas (incluso errores) dificulta la depuración y viola principios REST.

Ignorar caché: No configurar cabeceras Cache-Control, ETag o Last-Modified desperdicia ancho de banda y recursos del servidor.

Verbos en URLs: Rutas como /getUser o /createOrder son estilo RPC, no RESTful. Usa /users/:id con métodos HTTP apropiados.

Acoplamiento fuerte: Forzar a los clientes a conocer la estructura exacta de URL en lugar de seguir enlaces de hipermedia crea integraciones frágiles.

Cambios que rompen compatibilidad sin versionado: Cambiar esquemas de respuesta sin versionado de API rompe clientes existentes.

Estándares y RFCs

Standards & RFCs
1)RFC 7231- HTTP/1.1 Semantics and Content
2)RFC 7232- HTTP/1.1 Conditional Requests
3)RFC 7233- HTTP/1.1 Range Requests
4)RFC 7234- HTTP/1.1 Caching
5)RFC 6570- URI Template
6)RFC 5988- Web Linking

Términos Relacionados

Related Terms: