Cómo crear una API REST: diseño, seguridad y despliegue
Para crear una API REST, haz una lista de los recursos que gestiona tu app (usuarios, pedidos, reservas), asigna a cada uno una URL como /orders y /orders/{id}, y usa métodos HTTP para las acciones: GET para leer, POST para crear, PATCH para actualizar y DELETE para eliminar. Devuelve JSON con códigos de estado significativos, valida cada dato de entrada, exige autenticación y comprobaciones de permisos por registro en el servidor, y pagina las listas. Después documenta los endpoints y despliega la API detrás de HTTPS.
Esta guía cubre las decisiones de diseño, un conjunto de rutas trabajadas, prompts para un constructor de apps con IA como Mythex y los errores que provocan agujeros de seguridad. Si las APIs te resultan nuevas, empieza por qué es una API.
Cuándo necesitas una API REST
- Tu frontend web necesita guardar y cargar datos desde un servidor
- Una app móvil, un socio o una herramienta de automatización necesita acceder a tus datos
- Otros servicios te envían eventos (webhooks)
- Repartes el trabajo entre un equipo de frontend y uno de backend
REST es el estilo más común, pero no el único. REST frente a GraphQL explica cuándo un endpoint de consulta único y flexible encaja mejor.
Diseña primero: recursos y rutas
Escribe los sustantivos de tu app y lo que la gente hace con ellos. Para una app sencilla de reservas:
| Método | Ruta | Qué hace | Código de éxito |
|---|---|---|---|
GET | /api/bookings | Lista las reservas de quien llama (paginadas) | 200 |
POST | /api/bookings | Crea una reserva | 201 |
GET | /api/bookings/{id} | Obtiene una reserva | 200 |
PATCH | /api/bookings/{id} | Cambia algunos campos | 200 |
DELETE | /api/bookings/{id} | Cancela una reserva | 204 |
GET | /api/health | Comprobación de estado para monitorización | 200 |
Estas rutas se corresponden con crear, leer, actualizar y eliminar; consulta qué es CRUD. Convenciones que merece la pena seguir:
- Sustantivos en plural, sin verbos en las URL:
/bookings, no/getBookings. - Anida solo un nivel cuando aclara la propiedad:
/bookings/{id}/notes. - Las acciones que no son CRUD pueden ser subrecursos:
POST /bookings/{id}/canceles más claro que un PATCH mágico. - Nombres coherentes para los campos, como
created_aten todas partes.
Códigos de estado y errores
Usa los códigos HTTP estándar para que los clientes sepan qué ha pasado sin tener que interpretar texto:
| Código | Significado | Úsalo cuando |
|---|---|---|
| 200 | OK | Lectura o actualización correcta |
| 201 | Created | Un POST creó algo |
| 204 | No Content | Éxito sin nada que devolver |
| 400 | Bad Request | Los datos no superaron la validación |
| 401 | Unauthorized | No has iniciado sesión o el token no es válido |
| 403 | Forbidden | Has iniciado sesión pero no tienes permiso |
| 404 | Not Found | No existe, o quien llama no debe saber que existe |
| 409 | Conflict | Duplicado, o el hueco ya está reservado |
| 429 | Too Many Requests | Se ha superado el límite de peticiones |
| 500 | Server Error | Algo ha fallado en tu lado |
Devuelve los errores siempre con la misma estructura JSON, por ejemplo {"error": {"code": "slot_taken", "message": "Esa hora ya no está disponible."}}, y nunca incluyas trazas de error ni errores de la base de datos en las respuestas.
Opciones y compromisos
| Decisión | Opción sencilla | Alternativa |
|---|---|---|
| Dónde vive la API | Rutas de API en tu framework web | Un servicio de API separado, útil para varios clientes o con otro lenguaje |
| Autenticación | Cookies de sesión para tu propia app web | Tokens (bearer o claves de API) para apps móviles y terceros |
| Paginación | ?page=2&limit=20 | Por cursor (?after=...), más estable en listas grandes y cambiantes |
| Versionado | Ninguno hasta que tengas usuarios externos | /v1/ en la ruta cuando otros dependan de ella |
| Documentación | Un README con las rutas | Una especificación OpenAPI, que las herramientas convierten en documentación interactiva y en código cliente |
Paso a paso
- Enumera los recursos y las rutas como arriba, incluyendo quién puede llamar a cada una.
- Modela los datos en tu base de datos con los campos y relaciones que necesitas.
- Crea primero las rutas de lectura, y luego las de crear, actualizar y eliminar.
- Valida los datos en cada escritura con una librería de esquemas: campos obligatorios, tipos, longitudes, valores permitidos. Rechaza los campos desconocidos.
- Añade autenticación y, después, autorización por registro: cargar
/bookings/42debe comprobar que la reserva 42 pertenece a quien llama, no solo que alguien ha iniciado sesión. - Pagina cada lista y limita el tamaño de página.
- Limita las peticiones del inicio de sesión y de las rutas costosas. Consulta límites de peticiones.
- Configura CORS solo si navegadores de otros dominios deben llamar a la API, y enumera explícitamente esos orígenes. Cómo solucionar errores de CORS explica los errores que vas a ver.
- Escribe documentación y pruebas para cada ruta, incluidos los casos de fallo.
- Despliega con los secretos en variables de entorno, HTTPS, registros y una comprobación de estado.
Prompts para tu creador con IA
Andamiaje:
Crea una API REST para reservas con estas rutas: GET /api/health, GET /api/bookings (paginada, máximo 50 por página), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Guarda los datos en nuestra base de datos. Valida los cuerpos de las peticiones con una librería de esquemas y rechaza los campos desconocidos. Devuelve los errores en JSON como {"error": {"code", "message"}} con los códigos de estado correctos (400, 401, 403, 404, 409). Guarda los secretos en variables de entorno.
Seguridad:
Exige inicio de sesión en todas las rutas de reservas. En cada lectura, actualización y eliminación, comprueba en el servidor que la reserva pertenece al usuario actual; si no, devuelve 404. Nunca aceptes IDs de usuario ni roles del cuerpo de la petición. Limita POST /api/bookings a 20 por minuto por usuario. Registra los errores en el servidor sin devolver trazas de error.
Documentación:
Escribe una descripción OpenAPI de estas rutas y un README breve con ejemplos de peticiones y respuestas para cada una.
Probar tu API
Pruébala desde fuera del frontend, porque los atacantes lo harán:
- Cada ruta funciona con datos válidos y devuelve la estructura y el código documentados
- Los campos que faltan o no son válidos devuelven 400 con un mensaje claro
- Sin token, todas las rutas protegidas devuelven 401
- Si el usuario A pide por ID el registro del usuario B, obtiene 404 o 403
- Las listas están paginadas; un
limitenorme se limita - Los duplicados o conflictos al crear devuelven 409, no 500
- Los límites de peticiones devuelven 429
- Las respuestas de error no contienen trazas, SQL ni secretos
- CORS solo permite los orígenes que pretendes
Errores habituales
- Comprobar el inicio de sesión pero no la propiedad. El agujero más común de una API: cualquier usuario con sesión puede leer cualquier registro cambiando el ID.
- Confiar en el cliente. Los precios, los roles y los IDs de usuario del cuerpo de la petición pueden editarse.
- Devolver filas completas de la base de datos. Se filtran hashes de contraseñas y campos internos. Elige qué incluye cada respuesta.
- Listas sin límite. Una petición que pida todos los registros puede ralentizar toda la app.
200 OKcon un error dentro. Los clientes y la monitorización no pueden saber que ha fallado.- CORS configurado para permitirlo todo en una API que usa cookies.
- Sin comprobación de estado ni registros, así que te enteras de las caídas por los usuarios.
Para una revisión más amplia antes del lanzamiento, consulta la lista de comprobación de seguridad para apps creadas con IA.
Crear una API REST en Mythex
Puedes pedirle a Mythex una API como parte de tu app o como servicio propio. La receta de la documentación API REST como backend incluye un prompt inicial: indica tu framework y tus rutas, pide errores JSON claros, guarda los secretos en variables de entorno e incluye un Dockerfile. Los backends en contenedor en Node, Python, C#, Java y otros se publican mediante un Dockerfile, y Mythex se encarga del despliegue desde Publicar (backends de API). Un proyecto puede tener una web y un servidor de API en paralelo, y puedes cambiar entre ambos en la vista previa. Guarda las claves como secretos del proyecto, y si la API necesita una base de datos, pídela en el chat: cada proyecto puede tener su propia base de datos Postgres, incluida en todos los planes. El agente puede probar la API por ti y, en Pro, puedes editar el código tú mismo en el editor y la terminal, o mantenerlo con sincronización bidireccional con GitHub. Para tareas programadas alrededor de tu API, consulta cómo ejecutar tareas en segundo plano.
Preguntas
¿Qué es una API REST?
Una API REST es la forma en que los programas trabajan con los datos de tu app a través de HTTP. Cada tipo de dato es un recurso con su propia URL, como /orders, y los métodos estándar actúan sobre él: GET para leer, POST para crear, PATCH o PUT para actualizar y DELETE para eliminar. Los datos suelen enviarse en JSON.
¿En qué lenguaje debo crear una API REST?
Elige lo que tú o tu equipo sepáis mantener. Node.js con Express o Fastify, Python con FastAPI y los frameworks de C# o Java funcionan bien. Las reglas de diseño para rutas, códigos de estado, validación y autenticación importan más que el lenguaje. Mythex ejecuta APIs en Node, Python, Java, C# o cualquier cosa que funcione como servidor web desde un Dockerfile, así que puedes elegir el que ya conozcas.
¿Cómo protejo una API REST?
Exige autenticación en cada ruta que no sea pública, comprueba en el servidor que quien llama puede acceder a cada registro concreto, valida todos los datos de entrada, usa HTTPS, limita el número de peticiones y guarda los secretos en variables de entorno. Nunca confíes en los IDs ni en los roles que envía el cliente.
¿Necesito un backend separado para una API REST?
No siempre. Frameworks como Next.js pueden servir rutas de API junto a las páginas. Un servicio de API independiente tiene sentido cuando varios clientes (web, móvil, socios) lo usan, o cuando necesita su propio lenguaje o escalado. En Mythex, una web y una API pueden convivir en un mismo proyecto y publicarse juntas.