Una API es una promesa. Otros desarrolladores construyen sobre ella, así que cada cambio puede romper la aplicación de alguien. Por eso las pequeñas decisiones de diseño importan pronto, cuando es barato corregirlas.

A continuación encontrarás los hábitos que mantienen una API limpia a medida que crece. Cada uno viene con un breve ejemplo.

REST en breve

REST es un estilo para construir API web. Tratas los datos como recursos, como usuarios o pedidos. Cada recurso tiene una URL. Usas métodos HTTP estándar para leerlo o cambiarlo. Las respuestas suelen ser JSON.

1. Nombra tus URL con sustantivos

La URL debe decir qué es la cosa. El método HTTP dice qué hacer.

• Usa sustantivos en plural: /orders, no /order.
• Usa minúsculas y guiones: /order-items.
• Muestra las relaciones con anidación, pero sin pasarte: /users/5/orders.

2. Usa correctamente los métodos HTTP y los códigos de estado

Para los problemas, elige el código que cuente la historia real:

• 400 Bad request: la entrada es incorrecta.
• 401 Unauthorized: el usuario no ha iniciado sesión.
• 403 Forbidden: ha iniciado sesión, pero no tiene permiso.
• 404 Not found: el recurso no existe.
• 409 Conflict: la acción choca con el estado actual.
• 429 Too many requests: ve más despacio.
• 500 Server error: algo se rompió en tu lado.

Nunca devuelvas 200 OK con un mensaje de error dentro. Confunde a los clientes y a las herramientas.

3. Devuelve errores claros y consistentes

Elige un formato de error y úsalo en todas partes. Incluye un código corto, un mensaje legible y, cuando sea útil, el campo que falla.

HTTP/1.1 422 Unprocessable Entity
{
  "error": {
    "code": "invalid_email",
    "message": "La dirección de correo no es válida.",
    "field": "email"
  }
}

No filtres trazas de pila ni detalles de la base de datos en los errores. Regístralos en el servidor.

4. Pagina, filtra y ordena las listas

Nunca devuelvas una lista enorme de golpe. Es lenta y desperdicia ancho de banda. Usa límites y un cursor o número de página.

GET /orders?status=paid&sort=-created_at&limit=20&cursor=eyJpZCI6MTAwfQ

La paginación por cursor se mantiene rápida y estable incluso cuando llegan filas nuevas. Los números de página son más simples y sirven para conjuntos de datos pequeños.

5. Versiona tu API

Algún día necesitarás cambiar cosas. El versionado permite que los clientes antiguos sigan funcionando mientras los nuevos avanzan. La forma más común es en la URL:

https://api.example.com/v1/orders

Añade una nueva versión solo para cambios incompatibles. Añadir un campo nuevo no es un cambio incompatible, así que mantenlo en la misma versión. Avisa a los usuarios con antelación antes de retirar una versión antigua.

6. Protege la API

• Usa solo HTTPS. Sin excepciones.
• Usa autenticación probada. OAuth 2.0 o tokens de corta duración superan a los esquemas caseros.
• Comprueba los permisos en cada solicitud. No confíes en el cliente.
• Valida toda la entrada. Comprueba tipo, longitud y formato en el servidor.
• Añade límites de frecuencia. Evita abusos y protege tus servidores.
• Mantén los secretos fuera de las URL. Las URL acaban en los registros.

7. Mantenla rápida

• Usa cabeceras de caché como ETag y Cache-Control para los datos que rara vez cambian.
• Comprime las respuestas con gzip o Brotli.
• Deja que los clientes pidan solo los campos que necesitan, por ejemplo ?fields=id,name.
• Evita las llamadas lentas a la base de datos añadiendo los índices adecuados.

8. Documenta y prueba la API

Una API sin documentación es un juego de adivinanzas. Descríbela con el formato OpenAPI para poder generar documentación y código de cliente. Muestra ejemplos de solicitudes y respuestas de cada endpoint.

Después pruébala. Comprueba los códigos de estado, la forma de la respuesta y los casos de error. Una herramienta como Postman lo hace sencillo, y nuestra guía de pruebas de API con Postman te muestra cómo. Si quieres probar recorridos completos de usuario entre servicios, lee nuestros consejos sobre pruebas end-to-end.

Preguntas frecuentes

Sigue aprendiendo