Iniciar sesión / Registrar Cuenta

API

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

Jump to section

La expresión "diseño de API" hace referencia al proceso de desarrollo de las interfaces de programación de aplicaciones (API), que presentan las funciones de las aplicaciones y los datos para que los usuarios y los desarrolladores puedan utilizarlas. Las API son importantes para las empresas modernas, ya que permiten incorporar funciones 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 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 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 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í. 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 de tecnologías móviles y de aplicaciones, y admitir la conexión con más 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 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.Dada la singularidad del contenido, los datos y los servicios, el acceso a la API puede ser sumamente valioso.

A la hora de decidir qué deben ofrecer las API a la 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 los 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 medimos el éxito en relación con los objetivos empresariales que se establecieron?

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, 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 también integre a más personas, como miembros del equipo comunitario y de asistencia, especialistas 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 la propuesta de valor de la API no es adecuada (o no existe), 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 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 específicos 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
  • 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 estos puntos, considere los aspectos más generales y enumere todo lo que podría ser útil para el cliente, como el soporte, la documentación o los portales para desarrolladores. A continuación, especifique cómo pretende eliminar o reducir los contratiempos que experimentan los usuarios de las API al momento de realizar un trabajo, ya sea antes, durante o después, o aquellos aspectos que les impiden hacerlo. 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 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 precisió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 a los usuarios adecuados.

Una vez que sintetice y resuma las afirmaciones de correspondencia en un argumento general, este será la propuesta de valor de la 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 opción de mensajería de texto confiable, garantizada 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 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 de API 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 según la relación de los usuarios con la empresa (son clientes actuales, partners, desarrolladores externos), su función (científicos de datos, desarrolladores de tecnología móvil, personal de operaciones) y 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 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 debilidad, una oportunidad de ingresos, etc.) y del aspecto que se busca mejorar para el usuario (la velocidad, los ingresos, el ahorro de costos, la posibilidad de generar innovaciones, etc.).
  3. ¿Cuáles son los casos prácticos 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 con 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 aumentar el valor para el usuario a lo largo del 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 la forma en que la API puede aportar valor dentro de la empresa.

Un modelo comercial claro desde el comienzo

La definición del valor de la API es un aspecto importante en el diseño del programa basado en API. Sin embargo, las API también generan costos, lo cual debe compensarse con el valor. El valor debe ser real aunque no pueda medirse en términos monetarios. 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, cuáles son los beneficios que ofrece la API y 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.

Diseño e implementación según 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 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 tiene 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.

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

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 sea menos frecuente, pero que se deba abordar 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 no se debería seguir esta tendencia solo por eso. 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?Las API deberían contar con el respaldo de una capa que se extraiga de su modelo de datos real. Como regla general, no implemente una API que se dirija directamente a su base de datos (aunque sí 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 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 ese caso, será necesario comunicar con claridad este plan de forma interna y externa.

Enfoque en la experiencia del desarrollador

Un indicador fundamental 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 con mínima viabilidad 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.

Se recomienda cubrir tantos aspectos del proceso de participación del desarrollador como sea posible a la hora de definir el alcance del indicador TTFHW. 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 no tener ninguno), el acceso a las 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 si se utilizan a nivel interno.La complejidad de la implementación dependerá del público.

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. Es necesario que los desarrolladores puedan acceder a la API y comenzar a utilizarla con facilidad y rapidez.

El indicador 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 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, quienes suelen tener sus propios medios y redes de comunicación y de 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 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. Es recomendable tener presentes los indicadores de TTFHW y TTFPA a la hora de considerar los elementos que se agregarán a la experiencia del desarrollador (como los portales), así como todos los aspectos de la API que se modificarán.
  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 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 la flexibilidad suficiente como para que la API atraiga a los desarrolladores?Lo ideal es que haya encontrado 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 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

Plataforma de integración distribuida y diseñada en 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 producto complementario de Red Hat OpenShift Dedicated.