Instruct ApSSoftware diseñado con cuidado, desde la primera idea hasta el mantenimiento a largo plazo.
ES
Diseño de APIs

Desarrollo de APIs: diseñar interfaces que otros desarrolladores valorarán

Publicado

7 min de lectura

Una API es un producto con sus propios usuarios, y esos usuarios son desarrolladores que la juzgarán en cuestión de minutos. Las decisiones sobre nombres, errores y estructura marcan cada integración posterior, así que conviene pensarlas bien antes de publicar el primer endpoint.

Partir de las necesidades del consumidor

Antes de escribir un solo endpoint, dedica tiempo a quienes lo van a utilizar. Pregunta qué intentan lograr, qué datos necesitan en una sola petición y dónde esperan encontrar fricciones. Una API diseñada desde dentro suele reflejar las tablas de tu base de datos y los módulos internos, lo que rara vez coincide con la forma en que alguien construye una funcionalidad encima de ella.

Intenta escribir primero algunos escenarios de uso realistas en papel. Recorre los pasos que seguiría un consumidor para completar una tarea habitual y observa dónde necesitaría llamadas adicionales o adivinar. Esos vacíos indican dónde la interfaz debería ser más sencilla o dónde un endpoint dedicado ahorraría tiempo a todos.

También conviene separar lo que el consumidor necesita hoy de lo que imaginas que podría necesitar más adelante. Diseñar para funcionalidades hipotéticas tiende a engordar la interfaz y deja opciones que nadie usa. Empieza con la superficie más pequeña que resuelva el problema real y deja que las peticiones genuinas orienten lo que añadas después.

Elegir nombres de recursos claros y predecibles

Los nombres de los recursos son el vocabulario de tu API, así que trátalos con el mismo cuidado que a una etiqueta de interfaz de usuario. Usa sustantivos para los recursos y deja que los métodos HTTP expresen la acción, de modo que un desarrollador pueda deducir que un GET sobre una colección lista elementos y que un POST crea uno. Mantén el estilo de nombres coherente en toda la interfaz, ya sea con palabras en minúscula, guiones o un patrón específico.

Los sustantivos en plural para las colecciones suelen leerse con más naturalidad, y las rutas anidadas solo funcionan bien cuando la relación es realmente jerárquica. Una ruta que se hunde varios niveles resulta difícil de recordar y incómoda de cambiar más adelante. En caso de duda, aplana la estructura y vincula los recursos relacionados mediante identificadores o parámetros de consulta.

La previsibilidad importa más que la ingeniosidad. Si un endpoint usa un campo llamado customerId y otro usa customer_ref para el mismo concepto, todos los desarrolladores tropezarán con esa incoherencia. Acuerda un pequeño conjunto de convenciones, escríbelas y aplícalas en todas partes, incluidos los parámetros de filtros, ordenación y paginación.

  • Usa sustantivos para los recursos y métodos HTTP para las acciones
  • Mantén la coherencia entre las formas singular y plural en las rutas
  • Elige un único estilo de mayúsculas para rutas, parámetros y campos
  • Evita el anidamiento profundo; vincula los recursos relacionados
  • Nombra los parámetros de consulta de la misma forma en cada endpoint

Gestionar los errores de forma coherente

Los errores son el punto donde muchas APIs pierden la confianza de sus usuarios. Una respuesta con estado 200 que oculta un fallo, o un 500 genérico sin explicación, obliga al consumidor a adivinar qué salió mal. Usa los códigos de estado HTTP según su significado y reserva los errores de servidor para fallos reales de tu lado, no para datos de entrada no válidos enviados por quien llama.

Acompaña cada error con un cuerpo que tenga siempre la misma estructura. Un código legible por máquina permite que el software cliente reaccione de manera adecuada, mientras que un mensaje breve y comprensible para las personas ayuda al desarrollador que depura el problema. Indicar el campo que provocó un error de validación ahorra un tiempo sorprendente, sobre todo cuando una petición contiene muchos parámetros.

Piensa en los errores como parte del contrato, no como un añadido posterior. Una vez que los consumidores construyen lógica en torno a un código de error concreto, cambiarlo supone un cambio que rompe la compatibilidad. Documenta los errores que puede devolver tu API, mantenlos estables con el tiempo y añade códigos nuevos en lugar de reutilizar los existentes.

Documentar los endpoints para que la gente realmente los use

Documentar una API no es un toque final que se añade cuando el código ya funciona. Es la parte del trabajo que decide si alguien llegará alguna vez a usar tus endpoints. Un desarrollador que llega a tu API quiere saber, en pocos minutos, qué hace, qué espera y qué devuelve. Si tiene que adivinarlo, adivinará mal y culpará a la interfaz en lugar de a su propia lectura. Trata la documentación como un producto en sí mismo, con el mismo cuidado que dedicas al código que hay detrás.

El buen material de referencia describe cada endpoint con la misma estructura: su propósito, sus parámetros, sus posibles respuestas y sus casos de error. Incluye una petición y una respuesta realistas para cada uno, copiadas de algo que realmente funcione. Explica el paso de autenticación una sola vez, con claridad, y enlázalo desde todos los lugares donde sea relevante. Los lectores hojean las páginas, así que coloca la tarea más habitual al principio de cada una.

Los ejemplos hacen más trabajo que la prosa. Un fragmento breve y funcional en el lenguaje que usan tus lectores les permitirá superar su primer problema más rápido que un párrafo de explicación. Mantén la documentación cerca del código para que cambie cuando cambie el código, y revísala como parte de cada publicación. La documentación desactualizada suele ser peor que no tenerla, porque lleva a las personas con total seguridad en la dirección equivocada.

  • Asigna a cada endpoint un propósito claro y una petición de ejemplo
  • Muestra respuestas realistas de éxito y de error una junto a otra
  • Explica la autenticación una vez y enlázala en todas partes
  • Guarda la documentación en el mismo repositorio que el código
  • Revisa la documentación en cada publicación

Versionar sin romper los clientes existentes

Cambiar una API que otras personas ya usan es una tarea delicada, porque cada cambio que haces debe ser asumido por alguien más. El hábito más seguro es tratar la interfaz publicada como una promesa. Añadir un campo opcional nuevo o un endpoint nuevo normalmente no rompe nada, mientras que renombrar un campo o cambiar el significado de un código de estado puede romper mucho. Antes de modificar algo, pregúntate quién depende del comportamiento actual y cómo le comunicarías el cambio.

Cuando un cambio es realmente incompatible, publícalo en una nueva versión y mantén la anterior en funcionamiento durante un período indicado. Incluye la versión en la ruta o en una cabecera, y sé coherente en el uso que haces de ella. Anuncia las obsolescencias con antelación, indica cuándo dejará de funcionar la versión antigua y ofrece a los clientes una guía práctica de migración en lugar de una advertencia escueta. Registrar qué clientes siguen llamando a la versión antigua te ayuda a decidir cuándo es seguro retirarla.

Versionar resulta más sencillo cuando reduces al mínimo el número de cambios incompatibles que haces. Diseña las respuestas de forma que los clientes puedan ignorar los campos que no reconocen, y evita exponer estructuras internas que quizá quieras modificar más adelante. Mantén un registro de cambios sincero sobre qué se movió y por qué. Una interfaz estable construida de este modo suele necesitar menos versiones a lo largo de su vida, y las que sí necesita resultan mucho menos dolorosas de introducir.

Proteger el acceso y limitar el uso indebido

Toda API pública necesita una respuesta deliberada a la pregunta de quién puede llamarla y con qué frecuencia. La autenticación indica quién hace la petición, y la autorización indica qué puede hacer; ambas deben aplicarse en el servidor y no confiarse al cliente. Usa estándares consolidados como OAuth 2.0 o esquemas basados en tokens en lugar de inventar los tuyos, y nunca coloques secretos en las URL, donde acaban en los registros y en el historial del navegador. Verifica cada petición como si viniera de alguien que aún no has comprobado.

La limitación de tasa protege tu servicio tanto de sobrecargas accidentales como de abusos deliberados. Establece límites por cliente o por clave, devuelve un código de estado claro cuando se alcance un límite e incluye cabeceras que indiquen al cliente cuándo puede volver a intentarlo. Valida las entradas de forma estricta, limita el tamaño de las cargas útiles y de los resultados paginados, y rechaza las solicitudes mal formadas desde el principio. Vigilar patrones inusuales, como un aumento repentino desde una misma clave, te da tiempo para reaccionar antes de que un pequeño problema se convierta en una interrupción.

La seguridad funciona mejor cuando está en capas y es sencilla. El cifrado en tránsito debe ser obligatorio, las claves deben poder rotarse sin tiempo de inactividad y el acceso debe seguir el principio de mínimo privilegio, de modo que cada clave solo pueda hacer lo que su propietario necesita. Consulta las recomendaciones de organismos reconocidos, como el proyecto OWASP API Security, que recoge las debilidades más comunes en la práctica. Revisa tus decisiones con regularidad, porque las amenazas y las bibliotecas de las que dependes no dejan de cambiar.

Puntos clave

  • Diseñar pensando en el consumidor Parte de lo que necesitan las personas que llaman a tu API para lograr sus objetivos, no de cómo está organizada tu base de datos.

  • Trata la interfaz publicada como una promesa Realiza cambios aditivos siempre que sea posible y versiona de forma abierta, con avisos claros de obsolescencia cuando una ruptura sea inevitable.

  • Seguro por defecto Aplica la autenticación, la autorización y los límites de tasa en el servidor, y mantén los secretos fuera de las URL y de los registros.

Fuentes

  1. Proyecto OWASP API Security

Este artículo es información general, no asesoramiento profesional.