Iniciar sesión / Registrar Cuenta

API

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

El término "diseño de API" hace referencia al proceso de desarrollo de las interfaces de programación de aplicaciones (API), que exponen las funciones de las aplicaciones y los datos para que los 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 conviene adoptar programas de API, sino cómo hacerlo. 

Un programa de API eficaz debe basarse en la estrategia corporativa general de una empresa y contribuir a sus objetivos. Sabrá que tiene los elementos que se necesitan para una gran 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 esta pregunta 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 es valiosa cuando se convierte en un medio que permite 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. Esto es cierto solo en los casos en que la API es un producto en sí. Sin embargo, 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 móvil y de las aplicaciones, y admitir la conexión con más dispositivos. Los beneficios empresariales deben ser lo suficientemente importantes para que la decisión de invertir en las API sea obvia para la empresa.

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 enfoque interno 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 si utiliza una API para permitir el acceso a ellos.Gracias al contenido, los datos y los servicios únicos, el acceso a la interfaz 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 lo siguiente:

  • ¿Qué tecnología se utiliza para diseñar las API?
  • ¿Cómo se diseñan las API?
  • ¿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 realizamos un seguimiento del éxito en relación con los objetivos comerciales que se han establecido?

El equipo de API

Un equipo de API está más estrechamente relacionado con uno de "productos"; ya sea que sus clientes sean internos o externos, usted está a cargo de diseñar, implementar, operar y optimizar la infraestructura de la que otras personas dependen.

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 también integre a más personas, como miembros del equipo comunitario y de asistencia, expertos en API, 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 buena asistencia 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 una API tiene una propuesta de valor errónea (o no tiene ninguna) será muy difícil o 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.

¿Qué significa esto para su API?

Encontrar y describir el valor de la API es un proceso iterativo. 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 integrarse con diferentes sistemas de envío de mensajes en función de la ubicación del usuario.
  • Garantizar la distribución segura 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 amenazas.
  • Si la confiabilidad satisface sus necesidades, deshacerse de otros equipos de almacenamiento.
  • 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 cliente 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. Describa cómo pretende generar algún tipo de beneficio para los usuarios de las API.

Al atravesar este proceso, los tres ejemplos anteriores podrían dar los siguientes resultados:

  • Una API de mensajería de varios canales con una sola llamada para enviar mensajes y la capacidad de volver a intentar 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 con eficacia 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 pueda 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 sí ofrezca grandes ventajas, pero que no esté dirigida al tipo correcto de usuarios.

Una vez que sintetice y resuma las afirmaciones de correspondencia en una sola general, esta se convertirá en la propuesta de valor de su API. En el caso de la API de mensajería que se menciona anteriormente, podría ser algo así:

Nuestra API de mensajería ofrece a los desarrolladores empresariales una funcionalidad de mensajería de texto confiable, garantizada y sin latencia para las aplicaciones comerciales más importantes. 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 simplemente una 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 aportar el valor de la API a otros equipos. Sin embargo, una propuesta bien definida facilita la adopción del programa de API y lo convierte en un contribuyente 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 se debe responder en función de la relación del usuario con su empresa (son clientes actuales, partners, desarrolladores externos), de su función (son científicos de datos, desarrolladores de tecnología móvil, personal de operaciones) y de sus requisitos o preferencias.
  2. ¿Cuáles son las debilidades de los usuarios que atenuamos o los beneficios que les ofrecemos? Esta pregunta se debe responder en relación con el negocio del cliente, los beneficios que brinda la propuesta de valor y los desafíos que presenta, y en función de si se satisface o no una necesidad fundamental (si es una debilidad o una oportunidad de ingresos) y de la métrica que se busca mejorar para el usuario (la velocidad, los ingresos, el ahorro de costos, la posibilidad de hacer algo nuevo, 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 creadas por 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 en el 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 dentro de la empresa.

Un modelo comercial claro desde el comienzo

Poder definir el valor de una API es un aspecto importante del diseño de su programa basado en API. Sin embargo, estas también generan costos, lo cual debe compensarse con el valor. Si bien el valor no puede medirse en términos monetarios, debe ser real. Por ejemplo:

  • ¿Cuál es el negocio principal actual de la empresa?
  • ¿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 cuáles son las funciones y las responsabilidades dentro de una empresa, y a quiénes se beneficia a partir del valor generado por la API y de qué manera. 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.

Diseño e implementación teniendo en cuenta el usuario

Un buen diseño de API tiene algunos principios básicos, que pueden diferir a la hora de su implementación. Analicemos la siguiente analogía: todos los automóviles tienen un volante, un pedal de freno y un acelerador. Es posible que la radio, los botones para encender las luces de emergencia o para abrir el maletero difieran un poco de un modelo a otro, pero es difícil 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 con 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. El más adecuado depende 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.

Flexibilidad

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 establecer 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 los 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.

Preguntas importantes 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? 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 ningún caso práctico que pueda ser menos frecuente, pero que se deba abordar de igual manera para permitir la innovación.
  2. ¿Implementamos las API de RESTful solo porque sí? Las API de RESTful están de moda en la actualidad, pero usted no debería seguir esta tendencia solo por eso. Aunque se ajustan muy bien a ciertos casos prácticos, algunos estilos de arquitectura, como GraphQL, 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 vaya directamente a su base de datos (aunque, en algunos casos, sí podría ser necesario).
  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 una API también debe abarcar 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 sus usuarios.
  5. ¿Sincronizamos el diseño de la API con el resto de nuestros productos? Si la API no es el único producto de su 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. Incluso en este caso, se debe comunicar con claridad este plan de forma interna y externa.

Obsesión con la experiencia del desarrollador

Una métrica clave que permite mejorar el diseño de la 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 alcanzar un producto mínimo viable con 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 inicio y el fin de la métrica 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 posible.

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. La demora excesiva del "momento del éxito" puede implicar la pérdida de desarrolladores.

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 un valor monetario o de algún otro tipo, como una forma de 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 tener un mecanismo de registro ligero (o ninguno), el acceso a funciones de prueba, excelente documentación y una gran cantidad de códigos fuente gratuitos y ordenados.

Se sugiere que la mayoría de los programas de API tengan un programa para desarrolladores, independientemente de si están expuestas al público en general, solo a los partners o a nivel interno.La complejidad de la preparación dependerá 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. Los desarrolladores deben poder acceder a la API y comenzar a utilizarla con facilidad y rapidez.

La métrica TTFHW es la mejor forma de cuantificar esta variable. Además, debería considerar optimizar el proceso de registro, mientras más fácil y rápido, mejor. Una práctica recomendada es 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 partners 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 su API que informe a los desarrolladores de la mejor manera.
  2. ¿Cuáles son nuestros TTFHW y TTFPA y cómo podemos reducirlos? Abordar el TTFHW de manera integral es una forma eficaz de mejorar la facilidad de desarrollo de la API. Se recomienda tener presentes 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), así como 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 trata del acceso a datos o API más confidenciales y, por eso, se podrían requerir acuerdos más formales. Para el resto de los casos, debería ser muy simple y directo, de modo que los desarrolladores puedan alcanzar el éxito rápidamente (TTFHW).
  4. ¿Ofrecemos la flexibilidad suficiente como para que la API atraiga a los desarrolladores?Es fantástico que haya encontrado la propuesta de valor adecuada, y que los desarrolladores se registren para su API. Tenga en cuenta que ayudarlos a tener éxito permitirá mantener y aumentar la cantidad de desarrolladores.
  5. ¿De qué manera ayudamos a los desarrolladores en caso de que enfrenten algún problema? Creemos en el enfoque de autoservicio, que le permitirá crecer. Muchas de las preguntas de los desarrolladores pueden responderse con una buena documentación, las preguntas frecuentes o 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.

Primeros pasos

Red Hat 3scale API Management

Permite que los usuarios internos y externos compartan, protejan, distribuyan, controlen y rentabilicen sus API con facilidad.

Red Hat Fuse logo

Una plataforma de integración distribuida y nativa de la nube que conecta las API on-premise, en la nube y en cualquier punto intermedio.

Servicio alojado y gestionado de administración de API que se distribuye como un producto complementario de Red Hat OpenShift Dedicated.