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 trabajado, prompts para un creador de apps con IA y los errores que provocan agujeros de seguridad. Si las API te resultan nuevas, empieza con 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 habitual, pero no el único. REST vs GraphQL explica cuándo encaja mejor un único endpoint de consulta flexible.

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:

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}/cancel es más claro que un PATCH mágico.
• 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 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

Paso a paso

1. Enumera los recursos y las rutas como arriba, 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. Crea primero las rutas de lectura, y luego las de crear, actualizar y eliminar.
4. Valida los datos 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 a quien llama, no solo que alguien ha iniciado sesión.
6. Pagina cada lista y limita el tamaño de página.
7. Limita las peticiones del inicio de sesión y de las rutas costosas. Consulta límites de peticiones.
8. 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.
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 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 limit enorme 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 OK con 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 pedir a Mythex una API como parte de tu app o como servicio independiente. 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 contenedores de Node, Python, C#, Java y otros se publican con 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 ellos 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 trabajo programado alrededor de tu API, consulta cómo ejecutar trabajos en segundo plano.

Preguntas