Header Ads Widget

Ticker

6/recent/ticker-posts

Diseñando la experiencia humana (desde cero)

 La consultora de API Leah Tucker comparte sus ideas sobre el diseño de API teniendo en cuenta la experiencia humana.

Una pregunta común que escuché en  la Cumbre de Plataformas de APIs nórdicas en Estocolmo y API the Docs en Amsterdam: ¿qué hace que un portal de desarrolladores sea exitoso ? Voy a intentar responderla aquí. Y animo a otros expertos atrevidos a participar en un buen debate a la antigua en 1-2-3.

1. El objetivo de un portal para desarrolladores es ayudar a sus desarrolladores a crear rápidamente una aplicación. ¿Bien o mal, gente?

Permítanme comenzar con mis antecedentes. De día, trabajo como ingeniero de integración de software para mi empresa: {sus} API . Por la noche, trabajo en otras cosas divertidas, explorando la integración de API para aplicaciones móviles. Trabajé como empleado o consulté como propietario de producto de un extenso programa de implementación de API empresarial, portal para desarrolladores de API, arquitecto de API y redactor técnico de API. Antes de eso, fui desarrollador web. El punto es que conozco una gran experiencia de desarrollador cuando veo una porque he trabajado todo el ciclo de vida de las API.

He tocado miles de API y he diseñado y documentado cientos. Soy silenciosamente despiadado. Despiadado con lo bien que se diseña y documenta una API. Soy cortésmente implacable. Sin perdón por cualquier dolor que pueda experimentar al integrar sus API, particularmente en múltiples colecciones de API dentro de una empresa. Entonces, cuando le digo a la gente lo que hago, me gusta decir: "Anticipo la experiencia humana de las API".

Estos son algunos de los elementos que considero más críticos para crear una aplicación móvil impulsada por API:

  1. Registro fácil (para obtener una clave API). Correo electrónico, nombre completo, nombre de usuario, contraseña. Eso es. No lo hagas doloroso. Hazlo facil. Aún mejor, permita que los desarrolladores ingresen solo su correo electrónico para registrarse. Envíeles un correo electrónico de activación de cuenta de marca con un clic en el botón "Activar". Si tiene éxito, dirija al usuario a su panel de usuario para obtener su clave API.
  2. Funcionalidad visual 'Pruébelo' (características de la aplicación). No obligue a los desarrolladores a clasificar sus parámetros de solicitud / respuesta de API línea por línea. ¡Permítales verlo en acción! Use menús desplegables para los filtros / parámetros de solicitud y muéstreles una demostración en tiempo real para ver el efecto.
  3. Precios . ¡Deje que los desarrolladores comiencen gratis (con acceso a todas sus API) pero muestre sus precios de producción! Y modelos de precios sencillos, por favor. Una empresa de nueva creación necesita evaluar los costos de la puesta en marcha, '¿necesito más financiación?' '¿Hay algún compromiso?' '¿Me atrevo a decir, puedo comprar actualizaciones de transacciones en su portal de desarrolladores, por favor?'
  4. Límites / estrangulamiento . Nuevamente, '¿qué obtengo gratis y qué sucede a medida que crezco?' "¿Puedo ver mis transacciones de API en su portal de desarrolladores, por favor?" Nuevamente, evaluando costos constantemente.
  5. SDK . '¿Cuánto tiempo va a tomar desarrollar esto?' Si tiene SDK, ¡casi nada de tiempo! Siempre que la documentación de la API esté en el paso 1-2-3. Los desarrolladores no llegan a su portal de desarrolladores esperando leer un libro; ellos escanean.

-HITO-

El desarrollador ha decidido probar sus API. Han creado una cuenta. Les ha ayudado a identificar los precios. Ahora pueden visualizar las funciones de la aplicación y tener SDK para implementarlas.

¿Quiere saber qué portal para desarrolladores tiene los 5 componentes? TomTom Developer Portal es un gran ejemplo. También hemos descrito otros 4 programas API que hacen muy bien la Experiencia de desarrollador aquí .

2. El éxito de un portal para desarrolladores viene de cero. (Usted, proveedor de tecnología API)

Arriba presentamos los cinco elementos críticos para ayudar a un desarrollador a construir rápidamente una aplicación. ¡Neat-o! ¿Y de dónde vino todo esto, de nuevo? Ciertamente no fue magia. Está construido a partir de una gran cantidad de trabajo que comenzó desde dentro de la empresa: la suya (proveedor de tecnología API).

Esto es lo que necesita internamente para que pueda crear estos 5 elementos críticos.

Registro sencillo (para obtener una clave API)

  1. Una API (generalmente) en el back-end para crear, almacenar y luego pasar estas credenciales de cliente a su portal de desarrolladores.
  2. ¿Cuántas API tienes de nuevo? Todos los gerentes de productos de API deben estar integrados con acceso abierto. De lo contrario, eso requiere un cambio organizativo y mensajes internos de los superiores.
  3. Su portal también debe seguir las reglas de GDPR . El nombre completo, el nombre de usuario y el correo electrónico es una categoría de "bajo riesgo", pero su equipo legal debe redactar los términos y condiciones de lo que recopila.
  4. Como parte de GDPR, también deberá cifrar los datos del usuario en los IDE locales de su equipo del portal de desarrolladores. Y proporcione a sus usuarios una forma de excluirse del seguimiento de sitios web (por ejemplo, Google Analytics) y anular la publicación de sus datos de su base de datos de usuarios si cancelan su cuenta.
  5. Sus redactores técnicos / de contenido deberían haber creado la copia para el correo electrónico de activación de la cuenta.
  6. Su departamento de marca corporativa probablemente quiera aprobar la paleta de colores que usa en el correo electrónico.

Tenga en cuenta; esto cubre solo una base para el registro de usuarios. El cambio de tendencia podría tardar hasta un año. No incluye desarrollo de frontend.

Funcionalidad visual 'Pruébelo' (características de la aplicación)

  1. Supongamos, por simplicidad, que está utilizando la interfaz de usuario de Swagger y que sus especificaciones utilizan Open API (también conocido como Swagger) 3.0. Deberá haber generado automáticamente o creado todas sus especificaciones manualmente. No he tenido mucha suerte con la precisión de los autogeneradores . (Si está leyendo este artículo, comparta sus secretos si conoce alguna herramienta o proceso).
  2. Supongamos que el proceso anterior es manual. ¿Tiene el conjunto de habilidades dentro de su organización para crearlos? Es probable que deba crearlos en nombre de sus equipos de API, revisar la precisión y luego hacer que esos equipos revisen las especificaciones nuevamente.
  3. Es posible que sus equipos de API no inviertan en la decisión empresarial de crear su elegante portal para desarrolladores. Si crea las especificaciones en su nombre, tiene entre "ahora" y el momento en que actualicen sus API para que estos equipos mantengan sus especificaciones. Nuevamente, esto puede requerir un cambio organizacional y mensajes internos de los superiores. Asumamos el éxito con esta iniciativa.
  4. Sus especificaciones Swagger ahora son parte de su portal de desarrolladores. ¿Qué tan buena es la documentación ? Ahora está al frente y al centro. La mayoría de los usuarios (excepto los ingenieros de integración de software más capacitados) lo considerarán parte de su portal. La documentación inadecuada afectará la opinión de los usuarios (por ejemplo, puntaje neto del promotor) de su portal. Es posible que necesite redactores técnicos para trabajar con sus equipos de API. ¿Pueden seguir manteniendo este nivel de calidad una vez que lo entregue? Nuevamente, cambio organizacional y mensajes internos de los superiores. Asumamos el éxito nuevamente.
  5. Finalmente, el aspecto demo que permite a los usuarios ver el efecto. Deberá integrar cada API en su mini aplicación web front-end. ¿Qué sucede cuando lanza una nueva función? (Nota: obtenga comentarios sobre sus API de este equipo de integración, sea quien sea. En particular sobre la documentación).
Lea también: Hermoso diseño de interfaz de usuario para portales de desarrolladores

Precios, límites y estrangulamiento

  1. ¿Todos sus clientes obtienen el mismo precio por una API? ¿Límites / estrangulamiento? ¿Existen diferentes niveles de precios? ¿Se le permite enumerar estos niveles públicamente?
    Todos estos factores afectan la organización y la documentación de manera diferente.
  2. Sus redactores de contenido / técnicos deben proporcionar documentación, independientemente. De lo contrario, no tener respuestas claras impedirá el proceso de creación de la aplicación, lo que afectará negativamente la experiencia general del usuario y la opinión de su portal.

SDK.

  1. Hay muchas formas diferentes de crear un SDK, incluso desde cero. Podría resultar costoso de desarrollar y mantener. Y mucho menos para que sus redactores técnicos documenten cada actualización. En el paso 1-2-3, ¿recuerdas? Mucho más difícil de documentar en la menor cantidad de palabras posible.
  2. Antes de seguir este camino (a menudo caro), investigue un poco. Descubra los lenguajes de programación más populares que utilizan sus clientes y el caso de uso más común para el tipo de aplicaciones que están creando. Por ejemplo, un desarrollador de aplicaciones móviles preferiría usar React.js porque es compatible con el lanzamiento de una tienda de aplicaciones de Android y Apple.

¡Uf! Su equipo del portal de desarrolladores de API, toda su organización y sus defensores ejecutivos tienen mucho trabajo por delante.

3. El éxito de sus API proviene de su máquina API bien engrasada. (Usted, proveedor de tecnología API)

De tu estrategia de diseño.

No puedo pensar en una sola empresa que no haya comenzado con un "equipo A". Este es un único equipo de ingeniería de software que implementa todas las API para una prueba de concepto para probar el mercado. A menudo escucho esto cuando me acerco al concepto de un modelo de datos estándar: “Estamos bien. No necesitamos pensar en un modelo de datos común. Solo somos nosotros ".

¡En efecto! Esta filosofía a menudo funciona cuando hay un equipo que realiza todo el desarrollo de la API. Sin embargo, no es escalable.

  • Piense en dos años en el futuro cuando su programa de API se cree oficialmente y más equipos comiencen a unirse a la mezcla. A menos que se haya implementado una estrategia de diseño, el resultado neto será que cada lado esté diseñando sus API en un silo.
  • En unos años, esto creará una divergencia de datos en la que las API dentro de la misma empresa eventualmente se volverán incompatibles entre sí. Por ejemplo, diferentes medios de autenticación, elementos de datos, códigos de estado, respuestas de error, incluso nombres de productos y terminales.

En esta coyuntura, su cliente se ve obligado a manejar todas sus discrepancias de diseño dentro de su aplicación, lo que conduce a una pila de deudas técnicas. Y mucho trabajo. Para una aplicación que usa llamadas a la API sin procesar, esto se convierte en una pesadilla de mantener.

Avance rápido dos años. Tres equipos de API han desarrollado cada uno 20 API para el dominio de "hoteles" con una buena adopción por parte de sus clientes. Un nuevo cliente ingresa a la mezcla y desea combinar las API de los tres equipos. El problema es que cada una de las API devuelve un nombre / formato de datos diferente para el parámetro de fecha de entrada del hotel:

  1. hotel_search: "checkInDateTime" como 2019/11 / 01_17: 20: 28 + 00: 00
  2. hotel_details: "check_in_date" como 2019-11-01 + "check_in_time" como 17: 20: 28 + 00: 00
  3. hotel_book: "check_in" como 2019-11-01T17: 20: 28 + 00: 00

Los desarrolladores de su aplicación ahora se ven obligados a convertir el formato dentro del backend de su aplicación para cada uno de sus puntos finales. Llamar para llamar. ¡Qué castigo!

  • Su aplicación llama a hotel_search para mostrar los resultados al usuario.
  • El usuario "hace clic" en uno de los hoteles para obtener más detalles. La fecha de entrada se debe analizar, convertir y pasar a la siguiente solicitud en hotel_details.
  • El usuario va a reservar el hotel. Probablemente lo haya descubierto; la aplicación necesita analizar, convertir y pasar la fecha / hora de entrada en el nuevo formato para la solicitud en hotel_book si el usuario decide reservar el hotel.

¡Esto es solo para un parámetro! Imagine la complejidad de esta aplicación si hay 50 o más discrepancias de datos en sus API. ¿La regla? Cuanto más coherente sea su diseño en todas las suites de API, más podrá reutilizar el código existente un desarrollador de aplicaciones. Parámetros de solicitud y respuesta, códigos de estado, respuestas a errores, el lote.

Avance rápido cinco años. Cien equipos de API han desarrollado 2000 API para los dominios de vuelos, hoteles, trenes, coches de alquiler y autobuses. Existen al menos cinco versiones significativas para cada API. El sesenta por ciento de sus clientes todavía usan v1. La máxima complejidad se ha convertido en una complicación importante para el éxito de sus clientes y el éxito de su programa API.

  • Su empresa ahora debe mantener cinco versiones de la misma API "viva", ya que es demasiado costoso para sus clientes actualizar la versión.
  • Recuerde, los desarrolladores de su aplicación están creando sus características y probablemente utilizando otros proveedores de tecnología API.
  • Se han vuelto tan agobiados por el mantenimiento de una aplicación tan compleja utilizando sus API que les llevaría años actualizar la versión.

No obligue a sus clientes a comprar en el mercado otros proveedores de tecnología API en su dominio. Elabore una estrategia de diseño dentro de su organización para garantizar la coherencia.

Programa de gestión de API. Lo adivinó: un programa de administración de API es un programa para administrar sus API. Elabore una estrategia de diseño dentro de su organización para garantizar la coherencia. Esto se puede hacer de muchas maneras: programáticamente y con "evangelistas" y arquitectos del diseño de API para liderar la estrategia de diseño en toda su organización. Si se realiza mediante programación, esto se ejecuta mejor a través de una plataforma de administración de API (por ejemplo, Apigee, Mulesoft, Kong) donde los equipos pueden reutilizar componentes de diseño estándar, como bibliotecas de datos. Además, las plataformas de administración de API consisten en una puerta de enlace API, que es infinitamente configurable, por lo que necesitará un equipo de puerta de enlace API para construirla, configurarla y mantenerla. Incluyendo la implementación de su estrategia de precios, limitación, autenticación de solicitudes y autorización.

4. El éxito de su programa API depende del éxito de su cliente.

Imagínese aprender a sí mismo la química orgánica. Algunos de nosotros probablemente podríamos hacerlo ... con algo de dolor y tortura. Pero ... ¿por qué? Ahora imagine por un momento que sus clientes pueden experimentar algunos problemas al integrar sus API. ¡Fácil de imaginar! De hecho, inevitable. Porque siempre pasa.

Recuerde, usted es el experto en sus API. Desarrolle un modelo de soporte con sus principales expertos en el ciclo.

Volver al centro de desarrolladores de TomTomcomo el mejor ejemplo de cómo hacer las cosas bien. Estoy trabajando en la integración de las API de TomTom para una aplicación de inicio de "proyecto favorito". Y decido seguir la ruta del SDK de iOS para ver si puedo ahorrar algo de tiempo. ¿Qué he hecho? Por lo general, trato con llamadas a API sin procesar. Odio rendirme, así que voy al portal de TomTom “soporte” para obtener ayuda. (Veremos cuánto tiempo más puedo tolerar el enfoque de integración SDK. En serio, guiones gráficos de una palabra. Está bien, lo siento; una palabra más ... interfaz). Envío un ticket el viernes por la noche, temprano en la mañana del sábado, y puse mi desarrollo en espera en el ínterin de una respuesta. ¡He aquí, recibo una respuesta de uno de sus principales expertos un sábado! De acuerdo, mi problema fue en parte un error del usuario (mi impulso e interpretación literal de la documentación), pero mi experto fue sumamente educado e informativo con su respuesta. Fijo.

Debe estar arraigado en la cultura de su empresa contar con los ingenieros necesarios y equipados para respaldar el éxito de sus clientes.

De su equipo de comunicaciones.

¡Informe a sus clientes sobre todas las funciones nuevas que está lanzando! Nuevamente, vaya al equipo de TomTom. La geovalla es una de las características principales que necesito. ¿Como si estuviera revisando constantemente su portal de desarrolladores para ver si ha lanzado nuevas funciones? UH no. Avísame por correo electrónico. Y aunque no necesito un historial de ubicación para mi aplicación, sí quiero bordes virtuales. ¿Puedo establecer bordes virtuales sin rastrear la ubicación del usuario? Voy a comprobarlo.

¡Informe a sus clientes cuando realice cambios en el código! Dios santo, de nuevo, estos chicos actúan juntos. ¡Te veo TomTom! Actualizando su estrategia de diseño de acuerdo con las mejores prácticas… ustedes, zorros inteligentes.

De su comunidad de relaciones con desarrolladores.

Antes de asistir a "API the docs" en Ámsterdam, no tenía idea de que TomTom tenía API, ni que podía usarlas para mi proyecto favorito. Ni que tuvieran un portal de desarrolladores hasta que conocí y conocí a Julija Babre. Después de que di un reconocimiento en LinkedIn de su portal para desarrolladores, el enjambre de su equipo de relaciones con desarrolladores se puso en contacto conmigo (algunos directamente) con su apoyo.

De su comunidad de gestión de productos.

¡Lo último, mira! Aquí hay una publicación del gerente de producto de TomTom Maps SDK para Web solicitando comentarios. Estos tipos son realmente buenos. Recibí esto por correo electrónico. (Una vez más, no me obligue a actualizar su portal de desarrolladores para comprobar si podría haber una actualización). Una publicación como esta no solo ayuda a sus desarrolladores a prepararse para la integración, sino que también le permite obtener comentarios sobre el producto y medir el éxito.

Convierta a sus adoptantes en defensores. Haz que se sientan parte de tu comunidad.

Conclusión

El portal para desarrolladores de TomTom "me vendió". Y también debe quedar claro en este artículo que TomTom ha equipado a su empresa desde cero para respaldar el éxito de su portal para desarrolladores, con sus cinco elementos críticos del portal para desarrolladores, una máquina API bien engrasada y relaciones con desarrolladores y comunidad de soporte. . Me hace "leal a la marca". Me dan ganas de ser una defensora. Y me da la confianza de que seguirán contribuyendo a asegurar mi éxito en la creación de mi aplicación.

Y así, amigos, es cómo se asegura el éxito de su portal para desarrolladores. Sea como TomTom. Tienes que diseñar para la experiencia humana desde cero (desde dentro de tu empresa).

Resumen de "Notas del acantilado"

  1. Casos de uso de aplicaciones . Investigue a sus clientes para identificar qué tipo de aplicación están creando sus clientes. Web, móvil? ¿Qué lenguajes de programación? Por ejemplo, los desarrolladores de Java (normalmente grandes empresas) se preocupan más por las convenciones de casos que otros programadores.
  2. Diseño de API consistente . Implemente una estrategia de diseño para garantizar la coherencia en su conjunto de API mucho antes de comenzar a pensar en exponer sus API al público en un portal para desarrolladores.
  3. Cambio organizacional . Consiga su organización a bordo. Aún mejor, ¡haga que sus ejecutivos se unan! Acceso abierto a sus API, modelos de precios transparentes / explícitos y contratación de las habilidades necesarias internamente para los casos de uso de su aplicación (por ejemplo, lenguajes de programación, SDK).
  4. Programa de gestión de API (y equipo) . Organice un programa de gestión de API interno para garantizar la coherencia de su estrategia de diseño. Esto puede ser a través de una plataforma de administración de API (por ejemplo, Apigee, Mulesoft, Kong) donde los equipos pueden reutilizar las bibliotecas de datos compartidas. Puede ser a través de la contratación de arquitectos "evangelistas" de diseño central para liderar esta estrategia de diseño en toda su organización. Refuerce esto mediante programación a través de una canalización de CI / CD a su portal de desarrollador.
  5. Equipo de puerta de enlace API . Si realiza esto utilizando una plataforma de administración de API (recomendado), necesitará ingenieros de plataforma y software para configurar y admitir su puerta de enlace API. Cosas como estrangulamiento, autenticación OAuth 2.0, solicitud de firma, nonce (para evitar ataques de reproducción).
  6. Equipo del portal de desarrolladores de API . Un portal para desarrolladores de API con una mini aplicación web front-end para cada endpoint (es decir, demostración visual) es increíblemente sofisticado. Vaya híbrido: externamente para construir e internamente (en consecuencia) para respaldar y mejorar continuamente su portal para desarrolladores. Recopile comentarios de los usuarios continuamente para medir el éxito. No se olvide del RGPD, recopile información mínima del usuario. (Nota: algunas plataformas de administración de API tienen integrado el componente del portal para desarrolladores).
  7. Equipo de gestión de producto . Informe a sus desarrolladores cuando una versión esté disponible (tan pronto como pueda) y obtenga comentarios antes de la disponibilidad general.
  8. Equipo de comunicaciones . Redactores de contenido de marketing para comunicaciones de marca con los clientes. Redactores de contenido para la copia de su portal. Los mejores escritores técnicos son capaces de escribir documentación de API y SDK en el paso 1-2-3.
  9. Modelo de éxito del cliente . Cree una comunidad de apoyo y relaciones con el desarrollador con personas centradas en su modelo organizativo para garantizar el éxito del cliente. Canalice los comentarios de los clientes en toda su organización.
  10. Portal de desarrolladores . Finalmente, inicie un portal para desarrolladores con los elementos críticos que los desarrolladores de su aplicación necesitan para construir y escalar su aplicación. Atención ejecutivos: De ello depende el éxito de su portal de desarrolladores y la fidelidad a la marca hacia su empresa.

Publicar un comentario

0 Comentarios