¿Cómo diseñar un API?

Una guía rápida y teórica

Photo by Med Badr Chemmaoui on Unsplash

En esta ocasión quise realizar un resumen del articulo citado a continuación, esto con el fin de tener condensada la información necesaria para generar un documento inicial de diseño de un API, sin la necesidad de leerlo a detalle y respondiendo solo una serie de preguntas en cada sección.

¿En qué consiste el diseño de API?

El diseño de un API eficaz debe basarse en la estrategia corporativa general de una empresa y contribuir a sus objetivos. Sabrás que tienes los elementos que se necesitan para una buena estrategia cuando puedas responder las siguientes tres preguntas de forma clara:

1. ¿Por qué queremos implementar las API?
2. ¿Cuáles son los resultados concretos a los que queremos llegar con estas API?
3. ¿Cómo pensamos ejecutar el programa de API para lograrlo?

⁉️ El motivo

• ¿Cuál es el valor de tu API?
• ¿Tienes un objetivo comercial? ¿Si? ¿Cuál es? ¿Deseas aumentar tus ingresos, aprovechar modelos comerciales nuevos, mejorar el tiempo de comercialización o desarrollar nuevo canales de distribución?
• ¿Tienes un objetivo tecnológico? ¿Si? Cuál es? ¿Deseas mejorar la integración de tecnologías móviles y de aplicaciones, o admitir la conexión con más dispositivos?

🎯 El objetivo

• ¿Cuáles son los resultados concretos a los que queremos llegar con estas API?
• ¿Qué hacen las API realmente y cómo influyen en la estrategia comercial general?

⚙️ El método

• ¿Qué tecnología se utiliza para diseñar las API?
• ¿Cómo se diseñan las API?
• ¿Cómo se mantienen las API?
• ¿Cómo se promocionan dentro de la empresa o cómo se comercializan al mundo exterior?
• ¿Cuáles son los recursos disponibles?
• ¿Quiénes deberían formar parte del equipo?
• ¿Cómo medimos el éxito en relación con los objetivos empresariales que se establecieron?

🧑🏼‍💻 El equipo inicial

El siguiente es un listado de perfiles o personas que deberías tener en cuenta para generar tu equipo de trabajo

• Una persona centrada en el producto que sea la responsable de la estrategia y los objetivos
• Miembros del equipo centrados en el diseño que garanticen el uso de las prácticas recomendadas en el diseño de API
• Ingenieros que pongan en marcha la tecnología de la API
• Miembros del equipo de operaciones que la ejecuten

🔍 ¿Cómo encontrar y describir el valor de la API?

El proceso

1. Describir el trabajo que los usuarios desean realizar.
2. Identificar los desafíos específicos que enfrentan los usuarios antes o después de realizar el trabajo, o durante el proceso en sí
3. Resumir los posibles beneficios para el usuario
4. Redactar varias afirmaciones que expliquen en detalle la correspondencia entre la API y el perfil del usuario

¿Cómo definir el valor de su programa de API?

1. ¿Quién es el usuario?
2. ¿Son clientes actuales, partners, desarrolladores externos?
3. ¿Cuál es su función? ¿Son científicos de datos, desarrolladores de tecnología móvil?
4. ¿Cuáles son sus requisitos o preferencias?
5. ¿Cuáles son las debilidades de los usuarios que atenuamos o los beneficios que les ofrecemos?
6. ¿Cuáles son los casos prácticos compatibles con su API?
7. ¿Cómo se puede aumentar el valor para el usuario a lo largo del tiempo? ¿Cuáles son los próximos hitos importantes en relación con los cambios internos o externos?
8. ¿Qué valor se genera para su empresa a nivel interno?

🎨 Diseño e implementación según el usuario

Principios básicos

• Simplicidad: Formato de datos, estructura del método, modelo de datos, autenticación, políticas de uso.
• Flexibilidad: ¿En qué se basa el espacio potencial de operaciones?

Preguntas que debe considerar

Para analizar detenidamente el diseño de su API, tenga en cuenta las siguientes cinco preguntas:

1. ¿Diseñamos la API para respaldar nuestros casos prácticos?
2. ¿Implementamos las API de RESTful solo porque sí?
3. ¿Expusimos nuestro modelo de datos sin pensar en los casos prácticos?
4. ¿Qué regiones geográficas son las más importantes? ¿Hemos planificado nuestros centros de datos en función de ellas?
5. ¿Sincronizamos el diseño de la API con el resto de nuestros productos?

📄 Recomendaciones

Durante su discurso en la O’Reilly Open Source Convention de 2012, John Musser destacó las cinco “claves” para una buena API:

1. Prestar un servicio valioso
2. Tener un plan y un modelo comercial
3. Permitir que sea simple, flexible y fácil de adoptar
4. Permitir su gestión y medición
5. Ofrecer buena asistencia a los desarrolladores

Referencias

• ¿En qué consiste el diseño de API? https://www.redhat.com/es/topics/api/what-is-api-design
• What Makes a Great Open API? https://www.slideshare.net/jmusser/what-makes-a-great-open-api