Buscar

Español

Español

Iniciar sesión

Iniciar sesión/Registrar

Websites

API

¿Qué es 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 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 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 el negocio principal de la empresa, no necesariamente la API. Una API es valiosa cuando se convierte en un medio para proporcionar tipos nuevos de acceso 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, este no es el caso 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 aplicaciones y la integración móvil, y admitir la conexión a 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 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 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 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 la cantidad de mensajes que se envían 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, minimizar la cantidad de ancho de banda de transferencia
  • Gestionar grandes cantidades de datos e intentar relacionarlos en tiempo real

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
  • Deshacerse de otros equipos de almacenamiento si la confiabilidad satisface sus necesidades
  • Desencadenar acciones basadas en los eventos de forma automática

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. 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, PagerDuty).
  • Una API de sincronización del almacenamiento con llamadas optimizadas para verificar con eficacia si se deben sincronizar versiones nuevas (por ejemplo, Bitcasa, Box).
  • Una API que agregue diversas fuentes de datos a un flujo configurable, que se pueda filtrar, probar y manipular con facilidad (por ejemplo, GNIP, DataSift).

Por último, un ejercicio útil de clarificación consiste en redactar varias afirmaciones que expliquen la correspondencia entre la API y el perfil del usuario con claridad. 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, 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, también es compatible con los kits de desarrollo de software (SDK) que abarcan los lenguajes de programación más populares 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 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 términos 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 mitigamos o los beneficios que les ofrecemos? Esta pregunta se debe responder en relación con el negocio del cliente, con los beneficios que ofrece 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 qué métrica del usuario se busca mejorar (la velocidad, los ingresos, el ahorro de costos, la posibilidad de hacer algo nuevo).
  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.

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, 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 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: todo automóvil tiene 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

La característica de simplicidad de la API puede contraponerse con la de flexibilidad. 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. Las API de RESTful se ajustan muy bien a algunos casos prácticos, pero hay otros que prefieren otros estilos de arquitectura.
  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 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 esté cerca de 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 contar con 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 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 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 y comenzar a utilizar la API fácil y rápidamente.

El TTFHW es la mejor métrica para medir el acceso. 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 sean capaces de 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? Esta es una forma eficaz de mejorar la facilidad de desarrollo de su API al pensar en el TTFHW completo. 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 para el acceso a los datos o las API más confidenciales, por lo que se podrían requerir acuerdos más formales. Para el resto de los casos, la integración debería ser muy simple y directa para 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 si encontró la propuesta de valor adecuada y si los desarrolladores se registran para su API. Tenga en cuenta que ayudarlos a tener éxito mantendrá 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 buena documentación, preguntas frecuentes o 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.

Comience ahora

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

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