Cómo crear una API REST: diseño, seguridad y despliegue

Para crear una API REST, enumera los recursos que gestiona tu app (usuarios, pedidos, reservas), asigna a cada uno una URL como /orders o /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 claros, valida cada 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 de ejemplo, prompts para un creador de apps con IA y los errores que provocan agujeros de seguridad. Si las APIs te son 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 otro de backend

REST es el estilo más común, pero no el único. REST vs GraphQL explica cuándo encaja mejor un único endpoint de consultas flexible.

Primero el diseño: recursos y rutas

Apunta los sustantivos de tu app y lo que la gente hace con ellos. Para una app sencilla de reservas:

Estas rutas se corresponden con crear, leer, actualizar y eliminar; consulta qué es CRUD. Convenciones que conviene seguir:

• Sustantivos en plural y sin verbos en las URLs: /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}/cancel es más claro que un PATCH con magia.
• Nombres coherentes para los campos, como created_at en 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:

Devuelve los errores siempre con una misma forma JSON, por ejemplo {"error": {"code": "slot_taken", "message": "Ese horario ya no está disponible."}}, y nunca incluyas trazas de error ni errores de base de datos en las respuestas.

Opciones y compromisos

Paso a paso

1. Enumera los recursos y las rutas como se ha visto, incluyendo quién puede llamar a cada una.
2. Modela los datos en tu base de datos con los campos y relaciones que necesitas.
3. Construye primero las rutas de lectura y después las de crear, actualizar y eliminar.
4. Valida la entrada en cada escritura con una librería de esquemas: campos obligatorios, tipos, longitudes, valores permitidos. Rechaza los campos desconocidos.
5. Añade autenticación y después autorización por registro: cargar /bookings/42 debe comprobar que la reserva 42 pertenece al que llama, no solo que alguien ha iniciado sesión.
6. Pagina todas las listas y limita el tamaño de página.
7. Limita las peticiones en el login y en las rutas costosas. Consulta límites de uso (rate limiting).
8. Configura CORS solo si navegadores de otros dominios deben llamar a la API, y enumera esos orígenes de forma explícita. Cómo corregir errores de CORS explica los errores que verás.
9. Escribe documentación y pruebas para cada ruta, incluidos los casos de fallo.
10. Despliega con los secretos en variables de entorno, HTTPS, registros y una comprobación de estado.

Prompts para tu creador de apps con IA

Estructura inicial:

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 forma 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
• El usuario A que pide por ID el registro del usuario B recibe 404 o 403
• Las listas están paginadas; un limit enorme se limita
• Los duplicados o conflictos al crear devuelven 409, no 500
• Los límites de uso 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 en una API: cualquier usuario con sesión puede leer cualquier registro cambiando el ID.
• Confiar en el cliente. Los precios, roles e IDs de usuario que llegan en el cuerpo de la petición se pueden modificar.
• Devolver filas completas de la base de datos. Los hashes de contraseñas y los campos internos se filtran. Elige qué incluye cada respuesta.
• Listas sin límite. Una petición que pide todos los registros puede ralentizar toda la app.
• 200 OK con un mensaje de error dentro. Los clientes y la monitorización no saben 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 pedir a Mythex una API como parte de tu app o como servicio propio. La receta de la documentación backend de API REST 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 gestiona el despliegue desde Publish (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. Para tareas programadas en torno a tu API, consulta cómo ejecutar tareas en segundo plano.

Preguntas