Definición
OPTIONS es un método HTTP que solicita información sobre las opciones de comunicación disponibles para un recurso o servidor. Devuelve qué métodos HTTP están soportados (GET, POST, PUT, DELETE, etc.) y otras capacidades sin realizar ninguna acción sobre el recurso mismo. OPTIONS es un método seguro: no modifica el estado del servidor.
El uso principal de OPTIONS son las peticiones preflight de CORS: cuando un navegador hace una petición cross-origin con cabeceras personalizadas o métodos distintos a GET/POST, primero envía una petición OPTIONS para verificar si la petición real está permitida. El servidor responde con cabeceras CORS indicando qué está permitido.
OPTIONS es esencial para la descubribilidad de APIs y la seguridad de CORS. Ayuda a los clientes a entender qué operaciones pueden realizar sobre un recurso antes de intentarlas, y los navegadores lo usan automáticamente para aplicar excepciones a la política del mismo origen.
Ejemplo
Descubrir Métodos Permitidos:
OPTIONS /api/users/123 HTTP/1.1
Host: api.example.com
// La respuesta muestra los métodos permitidos
HTTP/1.1 200 OK
Allow: GET, PUT, PATCH, DELETE, OPTIONS
CORS Preflight - Antes de Petición PUT:
OPTIONS /api/posts/456 HTTP/1.1
Origin: https://myapp.com
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: Content-Type, Authorization
// El servidor responde con cabeceras CORS
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://myapp.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 86400
Capacidades a Nivel de Servidor:
OPTIONS * HTTP/1.1
Host: api.example.com
// La respuesta muestra capacidades del servidor
HTTP/1.1 200 OK
Allow: GET, POST, OPTIONS
Analogía
Consulta de Menú de Restaurante: Antes de ordenar, preguntas “¿Qué platos sirven? ¿Qué métodos de cocción usan?” OPTIONS es como preguntar a un restaurante qué pueden hacer antes de hacer tu pedido. Te dicen sus capacidades sin cocinar nada.
Filtrado de Llamada Telefónica: Piensa en OPTIONS como cuando llamas a un negocio y un sistema automatizado te dice “Presiona 1 para ventas, 2 para soporte, 3 para facturación.” Te está diciendo qué operaciones están disponibles antes de que elijas una.
Verificación de Permisos: Como preguntar a un portero “¿Puedo traer a mi amigo? ¿Podemos usar zapatillas deportivas?” antes de entrar a un club. El portero te dice las reglas (respuesta OPTIONS) sin dejarte entrar aún.
Ejemplo de Código
// OPTIONS - Descubrir capacidades del recurso
OPTIONS /api/users/789 HTTP/1.1
Host: api.example.com
// Respuesta - Métodos permitidos
HTTP/1.1 200 OK
Allow: GET, PUT, PATCH, DELETE, OPTIONS
Content-Type: application/json
Content-Length: 0
// OPTIONS - CORS preflight (automático del navegador)
OPTIONS /api/posts HTTP/1.1
Host: api.example.com
Origin: https://myapp.example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Content-Type, X-Custom-Header
// Respuesta - Cabeceras CORS
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://myapp.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-Custom-Header, Authorization
Access-Control-Max-Age: 86400
Access-Control-Allow-Credentials: true
Vary: Origin
// Después de preflight exitoso, el navegador envía la petición real:
POST /api/posts HTTP/1.1
Host: api.example.com
Origin: https://myapp.example.com
Content-Type: application/json
X-Custom-Header: value
{"title": "New Post", "content": "..."}
// OPTIONS - Capacidades a nivel de servidor
OPTIONS * HTTP/1.1
Host: api.example.com
// Respuesta
HTTP/1.1 200 OK
Allow: GET, HEAD, POST, OPTIONS
Server: nginx/1.25.0
Content-Length: 0
// OPTIONS - Endpoint de documentación de API
OPTIONS /api/products HTTP/1.1
Host: api.example.com
Accept: application/json
// Respuesta - Capacidades detalladas
HTTP/1.1 200 OK
Allow: GET, POST, OPTIONS
Content-Type: application/json
{
"methods": {
"GET": {
"description": "List all products",
"parameters": ["page", "limit", "category"],
"authentication": false
},
"POST": {
"description": "Create new product",
"authentication": true,
"requiredRole": "admin",
"contentType": "application/json"
}
},
"endpoints": [
"/api/products",
"/api/products/{id}"
]
}
// OPTIONS - Rechazo de preflight CORS
OPTIONS /api/admin/users HTTP/1.1
Origin: https://untrusted.com
Access-Control-Request-Method: DELETE
// Respuesta - CORS bloqueado
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error": "cors_not_allowed",
"message": "Origin not permitted"
}
// OPTIONS - Método no permitido
OPTIONS /api/readonly-resource HTTP/1.1
// Respuesta
HTTP/1.1 200 OK
Allow: GET, HEAD, OPTIONS
Diagrama
sequenceDiagram
participant Browser
participant Server
participant Backend
Note over Browser: Usuario dispara POST cross-origin
Browser->>Server: OPTIONS /api/posts (preflight)
Note over Browser,Server: Verificar permisos CORS
Server->>Backend: Verificar política CORS
Backend-->>Server: Reglas de política
Server-->>Browser: 204 No Content + cabeceras CORS
Note over Server,Browser: Access-Control-Allow-*
Note over Browser: ¡Preflight pasó!
Browser->>Server: POST /api/posts (petición real)
Note over Browser,Server: Con cabeceras personalizadas
Server->>Backend: Procesar petición POST
Backend-->>Server: Recurso creado
Server-->>Browser: 201 Created
Note over Server,Browser: Respuesta real
Note over Browser: Alternativa: Preflight Fallido
Browser->>Server: OPTIONS /api/admin (preflight)
Server-->>Browser: 403 Forbidden
Note over Browser: Navegador bloquea la petición real
Note over Browser: Error en consola
Mejores Prácticas
- Implementar para todos los recursos: Soportar OPTIONS en cada endpoint
- Devolver 200 OK o 204 No Content: Respuestas exitosas estándar
- Incluir cabecera Allow: Listar métodos HTTP soportados
- Manejar preflight CORS: Responder con cabeceras Access-Control-*
- Cachear respuestas preflight: Usar cabecera Access-Control-Max-Age
- Mantenerlo ligero: OPTIONS debe ser rápido, sin cálculos pesados
- Documentar capacidades: Opcionalmente devolver información detallada de API en el cuerpo
- Soportar asterisco: OPTIONS * para capacidades a nivel de servidor
- No requerir autenticación: OPTIONS debe funcionar sin autenticación
- Validar origen: Verificar cabecera Origin para seguridad CORS
Errores Comunes
No implementar OPTIONS en absoluto, causando fallos de CORS. Requerir autenticación para peticiones OPTIONS (rompe preflight CORS). Devolver 405 Method Not Allowed en lugar de implementar OPTIONS. No incluir cabecera Allow en la respuesta. Olvidar Access-Control-Allow-Headers en respuesta de preflight CORS. Establecer Access-Control-Max-Age demasiado bajo, causando peticiones preflight excesivas. No manejar OPTIONS comodín * para capacidades del servidor. Incluir cuerpo de respuesta cuando debería usarse 204 No Content. No variar respuesta por cabecera Origin (problemas de caché). Codificar métodos permitidos en lugar de determinarlos dinámicamente. No soportar OPTIONS para todos los endpoints consistentemente.