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

El término diseño de API hace referencia al proceso de desarrollo de interfaces de programación de aplicaciones (API)que expone las funcionalidades de las aplicaciones y los datos para que las utilicen los usuarios y los desarrolladores. Las API son importantes para las empresas modernas, ya que permiten incorporar capacidades nuevas que abarcan desde las operaciones y los productos hasta las estrategias de asociación. No es exagerado decir que la mayoría de las empresas ya no preguntan si es conveniente contratar programas de API, sino cómo hacerlo.

Un programa de API eficaz debe basarse en la estrategia corporativa general de la empresa y contribuir a sus objetivos. Sabrá que tiene los elementos que se necesitan para una buena estrategia cuando pueda 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

Por lo general, las personas no suelen interpretar este aspecto de la manera correcta. En primer lugar, en vez de centrarse en el valor de la API, es útil considerar el valor de su efecto. No olvide que lo valioso es la actividad principal de la empresa, no necesariamente la API. Esta ofrece beneficios cuando se convierte en un medio para acceder de nuevas formas al valor actual que ofrece una empresa.

Otra idea errónea común es creer que una API solo tiene valor si los usuarios están dispuestos a pagar por ella. Esta creencia solo es correcta en los casos en que la API es un producto en sí, pero no es lo que ocurre en la mayoría de los modelos. Por lo general, las API impulsan alguna otra métrica, como las ventas, la derivación de afiliados, el conocimiento de la marca, etc. El valor de la API para los usuarios es el resultado de la llamada a la API (la solicitud del servicio y su respuesta), en lugar de la llamada en sí.

Según una encuesta de Cutter Consortium y Wipro a 152 empresas, los objetivos comerciales más comunes que impulsan la adopción de programas de API son desarrollar asociaciones nuevas, aumentar los ingresos, aprovechar los modelos comerciales nuevos, mejorar el tiempo de comercialización y desarrollar canales nuevos de distribución. Los principales objetivos tecnológicos son mejorar la integración de las tecnologías móviles y de las aplicaciones, y admitir la conexión con una mayor cantidad de dispositivos. Los beneficios para la empresa deben ser lo suficientemente importantes para que la decisión de invertir en las API sea obvia.

El objetivo

La segunda pregunta debe ser: ¿cuáles son los resultados concretos a los que queremos llegar con estas API? Es decir, "¿qué hacen las API realmente y cómo influyen en la estrategia comercial general?"

Tanto el concepto de enfoque interno como el de enfoque externo de una empresa permiten definir el objetivo de la API. El primero hace referencia a los recursos específicos y valiosos de una empresa. Cuanto más valiosos y exclusivos sean los servicios y los recursos que ofrece, más conveniente será la adopción de un programa de API.

Una empresa que posee datos únicos puede aprovechar este recurso permitiendo el acceso a él a través de una API. Gracias al contenido, los datos y los servicios únicos, el acceso a la API puede ser sumamente valioso.

A la hora de decidir qué deben hacer las API por una empresa,
es preciso analizar los dos enfoques. Por lo tanto, la decisión acerca del objetivo suele ser una combinación de ambos.

En definitiva, si bien es poco probable que el motivo cambie con frecuencia, el objetivo puede variar de forma significativa en función de los factores externos, como el mercado, las consideraciones técnicas o las condiciones económicas. La orientación interna sobre el valor de un recurso puede cambiar, lo que también podría influir en lo que debería lograrse con una API.

El método

La última pregunta, "¿cómo diseñar el programa de API para alcanzar nuestros objetivos?", se trata de la implementación y la ejecución.

Los equipos deben preguntarse:

• ¿Qué tecnología se utiliza para diseñar las API?
• ¿Cómo se crean?
• ¿Cómo se mantienen?
• ¿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 de API se relaciona más estrechamente con uno de productos. Ya sea que tenga clientes internos o externos, usted está a cargo de diseñar, implementar, gestionar y optimizar la infraestructura de la que dependen otras personas.

Al igual que los equipos de productos, los de API también pueden ser muy diversos. Sin embargo, por lo general, deben incluir 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 y miembros del equipo de operaciones que la ejecuten.

Con el tiempo, es posible que se incorporen otras personas, como miembros del equipo comunitario y de asistencia, especialistas en API y representantes de seguridad, entre otros.

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 asistencia sólida a los desarrolladores

La primera clave, prestar un servicio valioso, tiene especial importancia en el motivo de la adopción del programa de API. La propuesta de valor es el principal impulsor del éxito de la API. Si no es la adecuada o directamente no existe, será muy difícil o incluso imposible encontrar usuarios.

Casi cualquier empresa con un producto actual, ya sea digital o físico, puede generar valor
mediante una API, siempre que dicha API se vincule con ofertas actuales y las mejore. La API aportará valor siempre que esté estructurada de modo que abarque casos prácticos significativos para los desarrolladores.

Encontrar y describir el valor de la API es un proceso constante. El primer paso es describir el trabajo que los usuarios desean realizar. Por ejemplo:

• En casos de emergencia, enviar comunicados urgentes a los miembros del equipo de forma automática
• Realizar copias de seguridad de los archivos importantes para garantizar que nunca se pierdan
• Recopilar datos de muestra para detectar ciertos eventos

Luego, se deben identificar los desafíos particulares que enfrentan los usuarios antes o después de realizar el trabajo, o durante el proceso en sí:

• Garantizar la confiabilidad de los envíos con varios intentos, detectar fallas, preocuparse por el envío de una gran cantidad de mensajes en lugar de uno solo e integrar diferentes sistemas de mensajería en función de la ubicación del usuario
• Garantizar el envío seguro de los archivos y, a su vez, reducir la cantidad de ancho de banda de transferencia
• Gestionar grandes cantidades de datos e intentar relacionarlos de inmediato

El tercer paso es resumir los posibles beneficios para el usuario:

• Enviar otros tipos de notificaciones que creen oportunidades en lugar de advertir sobre las amenazas
• Deshacerse de otros equipos de almacenamiento cuando la confiabilidad satisfaga sus necesidades
• Desencadenar acciones de forma automática en función de los eventos

Cuando evalúe estas debilidades, piense en términos generales y enumere todo lo que un usuario podría utilizar, como el soporte, la documentación o los portales para desarrolladores. A continuación, especifique cómo pretende eliminar o reducir aquello que implica una molestia para los usuarios de las API al realizar un trabajo, ya sea antes, durante o después, o los aspectos que les impiden hacerlo. Por último, describa cómo pretende generar algún tipo de beneficio para los usuarios de las API.

Al llevar a cabo este proceso, los tres ejemplos anteriores podrían dar los siguientes resultados:

• Una API de mensajería de varios canales que requiera una sola llamada para enviar mensajes y que vuelva a enviarlos de forma automática hasta garantizar su entrega (por ejemplo, Twilio o PagerDuty).
• Una API de sincronización del almacenamiento con llamadas optimizadas para verificar de manera eficiente si se deben sincronizar versiones nuevas (por ejemplo, Bitcasa o Box).
• Una API que reúna diversas fuentes de datos en un flujo configurable que se puede filtrar, probar y manipular con facilidad (por ejemplo, GNIP o DataSift).

Por último, un ejercicio útil de clarificación consiste en redactar varias afirmaciones que expliquen en detalle la correspondencia entre la API y el perfil del usuario. Si le resulta difícil identificar estas afirmaciones, debe volver a considerar el modelo de la API. Tal vez deba agregar, revisar, perfeccionar o eliminar algunas de sus características. También es posible que la API ofrezca grandes ventajas, pero que no esté dirigida a los usuarios correctos.

Una vez que sintetice y resuma las afirmaciones de correspondencia en un argumento general, este se convertirá en la propuesta de valor de la API. En el caso de la API de mensajería que se menciona anteriormente, podría ser la siguiente:

Nuestra API de mensajería ofrece a los desarrolladores empresariales un servicio de mensajería de texto confiable, garantizado y sin latencia para las aplicaciones más importantes de la empresa. Además, es compatible con los kits de desarrollo de software (SDK) que abarcan los lenguajes de programación más conocidos para una integración rápida.

Tal vez piense que es demasiado trabajo para crear una simple API interna. Sin embargo, la clave es centrarse en el valor, incluso en los casos prácticos internos. Una propuesta de valor mal determinada generará dificultades para promocionar el valor de la API a otros equipos. En cambio, una propuesta bien definida facilita la adopción del programa y lo convierte en un aporte clave para la empresa.

Para definir el valor de su programa de API, tenga en cuenta estas cinco preguntas:

1. ¿Quién es el usuario? Esta pregunta debe responderse teniendo en cuenta la relación de los usuarios con la empresa (es decir, si son clientes actuales, partners, desarrolladores externos, etc.), su función (por ejemplo, si se trata de científicos de datos, desarrolladores de tecnología móvil, personal de operaciones, etc.) y sus requisitos o preferencias.
2. ¿Cuáles son las dificultades de los usuarios que resolvemos o los beneficios que les ofrecemos? Esta pregunta debe responderse en relación con la actividad, los desafíos y los beneficios del cliente que se definen en la propuesta de valor, y en función de si se satisface o no una necesidad fundamental (una dificultad, una oportunidad de ingresos, etc.) y del indicador que se busca mejorar para el usuario (la velocidad, los ingresos, el ahorro de costos, la posibilidad de generar innovaciones, etc.).
3. ¿Qué casos prácticos son compatibles con su API? Con ayuda de la propuesta de valor, identifique las soluciones a los desafíos de sus usuarios o las oportunidades que surgen a partir de la API que son más efectivas para la empresa y el usuario. Prepare la API para abordar esos casos prácticos.
4. ¿Cómo se puede ampliar el valor para el usuario con el tiempo? Planifique la propuesta de valor teniendo en cuenta los cambios a futuro. ¿Cuáles son los próximos hitos importantes en relación con los cambios internos o externos?
5. ¿Qué valor se genera para su empresa a nivel interno? Analice los beneficios internos y cómo la API puede aportar valor a la empresa.

La definición del valor de las API es un aspecto importante a la hora de diseñar el programa basado en ellas. Sin embargo, estas también generan costos, y esta consideración debe compensarse con el valor. Si bien el valor no puede medirse en términos monetarios, debe ser real. Por ejemplo:

• ¿Cuál es la actividad principal de la empresa en la actualidad?
• ¿Cómo se puede utilizar una API para acelerar o incrementar este negocio?

En algunos casos, las API pueden generar oportunidades comerciales totalmente nuevas fuera del modelo comercial actual de la empresa. Incluso en esos casos, las API suelen aprovechar los recursos o la experiencia actuales para crear oportunidades de formas diferentes.

En resumen, hay tres razones por las que es importante determinar el modelo comercial adecuado para diseñar programas de API efectivos:

1. Hace hincapié en el valor de la API para la empresa, lo cual impulsa la decisión de asumir un compromiso a largo plazo con el programa de API. Sin ese compromiso, rara vez se dispone de los recursos para llevar a cabo las tareas que se necesitan para establecer y ejecutar un programa de API eficaz.
2. Ayuda a definir la funcionalidad del producto, esencial para satisfacer las necesidades de terceros y generar negocios.
3. Garantiza que se preste atención a las funciones y las responsabilidades dentro de una empresa, así como a los beneficios que ofrece la API y a quién los percibe. Esto también implica definir qué beneficios obtienen los usuarios de la API y cómo se equilibra esto con los beneficios que obtiene el proveedor de la API.

Un buen diseño de API tiene algunos principios básicos, que pueden diferir a la hora de su implementación. Veamos la siguiente analogía: todos los automóviles tienen un volante, un pedal de freno y un acelerador. Es posible que la radio o los botones para encender las luces de emergencia o para abrir el maletero difieran de un modelo a otro, pero es poco probable que un conductor experimentado no sepa cómo conducir un automóvil de alquiler.

Este nivel de diseño "listo para conducir" es lo que buscan los grandes equipos de API: no tener que explicar el funcionamiento de la API al profesional experimentado para que pueda comenzar a utilizarla.

Simplicidad

La simplicidad del diseño de la API depende del contexto. Un diseño en particular puede resultar simple para un caso práctico, pero muy complejo para otro, por lo que se debe equilibrar el nivel de detalle de los métodos de la API. Resulta útil pensar en la simplicidad en varios niveles, entre los que se incluyen los siguientes:

• Formato de datos: compatibilidad con los formatos propietarios, XML, JSON o una combinación de ellos.
• Estructura del método: los métodos pueden ser muy genéricos y proporcionar un conjunto amplio de datos, o muy acotados para permitir solicitudes específicas. También se suelen adoptar en una determinada secuencia para abordar ciertos casos prácticos.
• Modelo de datos: el modelo de datos subyacente puede ser muy similar o muy diferente a lo que realmente se expone a través de la API. Esto tienen una repercusión en las capacidades de uso y de mantenimiento.
• Autenticación: los diversos mecanismos de autenticación tienen diferentes ventajas y desventajas. La elección del más adecuado dependerá del contexto.
• Políticas de uso: es preciso que sea sencillo trabajar con los derechos y las cuotas para los desarrolladores, los que a su vez deben ser fáciles de comprender.

Es posible que la simplicidad y la flexibilidad de la API no vayan de la mano. Al crear una API teniendo en cuenta solo la simplicidad, se corre el riesgo de que resulte demasiado personalizada y que se adecue solo a casos prácticos muy específicos, sin la flexibilidad suficiente para abarcar otros casos.

Para determinar la flexibilidad, primero averigüe en qué se basa el espacio potencial de operaciones, incluidos los sistemas y los modelos de datos subyacentes, y defina cuáles de esas operaciones son viables y valiosas. Para encontrar el equilibrio justo entre simplicidad y flexibilidad, haga lo siguiente:

• Intente descubrir las operaciones atómicas. Al combinarlas, se puede cubrir todo el espacio.
• Identifique los casos prácticos más comunes y valiosos. Diseñe una segunda capa de metaoperaciones que combine diversas operaciones atómicas para abordar estos casos prácticos.

Se podría decir que el concepto de hipermedia como motor del estado de la aplicación (HATEOAS) puede mejorar aún más la flexibilidad, ya que permite que se realicen cambios en el tiempo de ejecución en la API y en las operaciones del cliente. HATEOAS aumenta la flexibilidad al facilitar la creación de versiones y la documentación. Sin embargo, se deben tener en cuenta muchas preguntas al momento de diseñar una API.

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

1. ¿Diseñamos la API para respaldar nuestros casos prácticos? El siguiente paso luego de identificar los principales casos prácticos es diseñar la API de modo que los respalde. La flexibilidad es importante para no excluir aquellos que son menos frecuentes, pero que deben abordarse para posibilitar la innovación.
2. ¿Implementamos las API de RESTful sin un motivo definido? Las API de RESTful están de moda en la actualidad, pero no debería seguir la tendencia solo por esta razón. Aunque se ajustan muy bien a ciertos casos prácticos, hay algunos estilos de arquitectura, como GraphQL, que resultan mejores para otros.
3. ¿Expusimos nuestro modelo de datos sin pensar en los casos prácticos? Una API debería contar con el respaldo de una capa que se extraiga de su modelo de datos real. Como regla general, no implemente una API que acceda directamente a su base de datos (si bien podría ser necesario en algunos casos).
4. ¿Qué regiones geográficas son las más importantes? ¿Hemos planificado nuestros centros de datos en función de ellas? El diseño de la API también debe cubrir elementos no funcionales, como la latencia y la disponibilidad. Asegúrese de elegir centros de datos cuya ubicación geográfica sea cercana a la mayoría de los usuarios.
5. ¿Sincronizamos el diseño de la API con el resto de nuestros productos? Si la API no es el único producto de la empresa, asegúrese de que su diseño esté coordinado con el del resto de los productos. Es posible que decida separar el diseño de la API de los otros productos por completo. En ese caso, deberá comunicar este plan con claridad de forma interna y externa.

Un indicador fundamental para mejorar el diseño de las API y facilitar su adopción es el tiempo que toma crear un programa "Hola, mundo" (TTFHW). En otras palabras, ¿cuánto demora un desarrollador en lograr un producto mínimamente viable utilizando su API? Esta es una excelente forma de ponerse en el lugar de un desarrollador que desea probar su API para descubrir qué hace falta para que un producto funcione.

A la hora de definir el alcance del indicador TTFHW, se recomienda cubrir tantos aspectos del proceso de participación del desarrollador como sea posible. Luego, optimícelo para que sea lo más rápido y conveniente que se pueda.

La capacidad de cubrir el proceso de forma rápida también permite que el desarrollador confíe en que la API está bien organizada y que todo funcionará como se espera. Si retrasa demasiado el "momento del éxito", puede sufrir la pérdida del personal.

Además del TTFHW, se recomienda otra métrica: el "tiempo hasta la primera aplicación rentable" (TTFPA). Esto es más complicado, ya que "rentable" es una cuestión de definición, que depende de su estrategia comercial y de la API. Tener en cuenta esto es útil porque lo obliga a pensar en los aspectos relacionados con las operaciones de la API como parte del programa de API.

Estos son los dos principios básicos de la experiencia del desarrollador:

1. Diseñar un producto o un servicio que ofrezca un valor claro a los desarrolladores y que aborde una oportunidad o un desafío específicos. Puede ser valor monetario o de algún otro tipo, como aumentar el alcance, el conocimiento de la marca, la base de clientes, las ventas indirectas, la reputación del desarrollador o el mero placer de usar una buena tecnología que funcione correctamente.
2. Debe ser posible acceder al producto con facilidad. Esto incluye contar con un mecanismo de registro ligero (o directamente no tenerlo), acceso a las funciones de prueba, documentación de primer nivel y una gran cantidad de código fuente gratuito y ordenado.

Se sugiere que la mayoría de los programas de API tengan un programa para desarrolladores, independientemente de si sus API están expuestas al público en general, solo a los partners o a nivel interno. Las disposiciones pueden ser más o menos detalladas en función de la audiencia.

Portal para los desarrolladores

El portal para desarrolladores es el elemento clave de un programa de desarrolladores. Es el principal punto de partida para que se registren en la API, accedan a ella y la utilicen. Deben poder acceder a ella de forma sencilla y comenzar a utilizarla con facilidad y rapidez.

El indicador TTFHW es la mejor forma de calcular esta variable. También debería considerar optimizar el proceso de registro, ya que mientras más fácil y rápido sea, mejor. Se recomienda que los desarrolladores puedan invocar las API para analizar su comportamiento (solicitud y respuesta) sin necesidad de registrarse. Por otro lado, el contenido complementario (como las guías de introducción, la documentación de referencia de la API o el código fuente) es fundamental para reducir la curva de aprendizaje.

Aceleración mediante el ecosistema de partners

Como proveedor de una API, usted trabaja en un ecosistema de partners y proveedores. Estos suelen tener sus propios medios y redes de comunicación y distribución de contenido. Se recomienda identificar alianzas que puedan ser útiles para aumentar la adopción de su API. Por lo general, estas alianzas se encuentran cuando las API son complementarias y ofrecen valor a los desarrolladores cuando se combinan.

Cuestiones que debe considerar para evaluar la experiencia de los desarrolladores:

1. ¿Cómo explicamos el valor de la API en los primeros cinco minutos? Elabore un discurso breve acerca de la propuesta de valor de la API que esté especialmente dirigido a los desarrolladores.
2. ¿Cuáles son nuestros TTFHW y TTFPA, y cómo podemos reducirlos? Abordar el TTFHW de manera integral es una forma eficaz de facilitar el uso de la API para los desarrolladores. Se recomienda tener en cuenta las métricas de TTFHW y TTFPA a la hora de considerar los elementos que se agregan a la experiencia del desarrollador (como los portales), y todos los aspectos de la API que cambian.
3. ¿Cuál es el proceso de integración para los desarrolladores? ¿Es lo más sencillo posible? Debe ser acorde a los casos prácticos de su API. Está claro que el nivel de seguridad debe ser mayor cuando se accede a los datos o las API más confidenciales, por lo cual se podrían requerir acuerdos más formales. Para el resto de los casos, el proceso debería ser muy sencillo y directo, de modo que los desarrolladores puedan alcanzar el éxito rápidamente (TTFHW).
4. ¿Ofrecemos suficiente flexibilidad como para que la API atraiga a los desarrolladores? Es ideal que encuentre la propuesta de valor adecuada y que los desarrolladores se registren para su API. Tenga en cuenta que si los ayuda a tener éxito, podrá retener e incorporar personal.
5. ¿De qué manera ayudamos a los desarrolladores cuando enfrentan problemas? Creemos en el enfoque de autoservicio, que le permitirá crecer. Muchas de las preguntas de los desarrolladores pueden responderse si se consultan una buena documentación, las preguntas frecuentes y los foros. Sin embargo, el autoservicio tiene sus límites. Para las preguntas más detalladas y otras complicaciones, como los problemas de facturación, debe contar con algún tipo de mecanismo de soporte.
6. ¿Puede nuestra documentación respaldar la innovación? ¿Qué tipo de respaldo ofrecemos a los desarrolladores que se apartan de los casos prácticos comunes o que desean probar algo nuevo? Las mejores ideas pueden surgir en cualquier lugar.