Header Ads Widget

Ticker

6/recent/ticker-posts

Cree SDK coherentes y atractivos para sus API

La defensora de los desarrolladores, Lorna Mitchell, comparte sus pensamientos sobre lo que se necesita para generar SDK que los desarrolladores adorarán.

Como promotor de desarrolladores de un proveedor de API , me apasiona mejorar la experiencia del desarrollador para cualquiera que quiera utilizar nuestras API. Una excelente manera de facilitar que cualquier desarrollador integre su API en sus plataformas es proporcionar un SDK (Software Development Kit) para su pila de tecnología.



Un SDK es una biblioteca instalable (las nuestras son de código abierto) que cualquier desarrollador puede usar en su aplicación. Al proporcionar una biblioteca apropiada para la pila tecnológica, es mucho más sencillo para un desarrollador integrar su API de formas que sean familiares y estén bien integradas con su cadena de herramientas existente. Por ejemplo, puede utilizar convenciones que ya son prácticas comunes en una pila tecnológica en particular o integrarse bien con las herramientas principales para proporcionar autocompletado u otras comodidades.

Los buenos SDK ahorran tiempo y esfuerzo cognitivo cuando se integran con la API de un proveedor. Las grandes API son consistentes en todo momento y un placer de usar, ofreciendo un valor más allá de simplemente llamar a los puntos finales de API desde la pila de tecnología deseada. Entonces, ¿cómo inspiramos SDK consistentes y deliciosos?

Vea a Lorna Mitchell hablar sobre este tema en ASC 2020:

Conseguir coherencia

Crear una experiencia consistente y confiable en un SDK toma muchas formas. Es fundamental tener patrones comunes en las diferentes funciones para que, por ejemplo, la autenticación siempre se maneje de la misma manera o los datos siempre se devuelvan de manera predecible. También es importante que la relación con la API sea lo más estrecha posible. Se deben incluir todos los parámetros de la API y los campos de respuesta para que la integración de la API sea precisa y completa. Pocas cosas son más molestas que encontrar algunos campos, pero no el que necesitas en ese momento.

En Vonage, nos ayuda mucho no solo tener documentación detallada y precisa para todas nuestras API, sino también tener definiciones de OpenAPI para cada una. De hecho, esas descripciones de API detalladas y precisas impulsan la documentación de API detallada y precisa .

OpenAPI está diseñado para que las máquinas lo puedan leer; es un formato muy descriptivo y algo detallado (JSON o YAML). Se describe cada punto final , junto con los datos que espera recibir y las respuestas que se pueden devolver. Cada campo de la solicitud y la respuesta tiene información sobre el tipo y formato deseados, lo cual es útil. La magia está realmente en la descripción y especialmente en los ejemplos que se aplican a cada campo y a solicitudes y respuestas completas. Cuando miro una descripción de OpenAPI, puedo imaginar claramente la API detrás de ella. No es de extrañar por qué tantas organizaciones gravitan hacia OpenAPI como formato fuente para la documentación de API .

Lo que es suficientemente descriptivo para una excelente documentación de API es también un buen punto de partida para una herramienta generadora de código . Un generador de código puede entender cómo usar una API y generar una interfaz decente en la pila tecnológica elegida. Hay muchas herramientas de generación automática que admiten diferentes pilas de tecnología en diferentes grados, pero he estado usando el generador de OpenAPI y ha funcionado perfectamente bien. El generador acepta la descripción de OpenAPI como entrada y genera una biblioteca completa. ¿La mejor parte? ¡El README incluye un ejemplo de cómo usar lo que se generó!

La generación de código produce puntos de integración precisos y precisos para la API. Si la API cambia, quizás porque se agrega una nueva característica, el código se puede volver a generar para incluir la actualización. Esto suena genial, ¿verdad? Bueno ... el código escrito por máquinas termina luciendo exactamente como cabría esperar, no es nada divertido de usar.

Deleite inspirador

Para dar a los desarrolladores un valor más allá de lo que podrían lograr generando el código ellos mismos, debemos pensar más allá de lo que una máquina puede hacer con un archivo OpenAPI . (Aparte: está publicando sus definiciones de OpenAPI públicamente para sus comunidades de desarrolladores, ¿verdad?). Como cuando se desarrolla cualquier otro tipo de software, un excelente punto de partida es ponerse en el lugar del usuario.

¿Cuál es el contexto de ese individuo? ¿Cuál es su objetivo y cuál es la forma más útil de ayudarlos a lograrlo? A menudo también confío en el "principio de la mínima sorpresa" en esta etapa. No tiene sentido crear un enfoque genuinamente innovador para la inicialización si cada desarrollador que llega a usarlo intenta, falla y va en busca de su documentación o de su competidor.

El deleite está en gran medida en el ojo del espectador, o al menos en sus tareas laborales completadas. Al producir una experiencia de desarrollador intencional y reflexiva en sus SDK, los desarrolladores se sorprenderán gratamente de su progreso: ese rumor positivo permanece con ellos.

Donde el código generado por la máquina y las experiencias de los desarrolladores chocan

Hasta ahora he hablado sobre el código generado clínicamente preciso pero sin alegría, y sobre las agradables experiencias de usuario en las que un desarrollador puede encontrar instintivamente el camino a través de la tarea en cuestión. Estas dos cosas no son iguales entre sí, y es posible que se pregunte si juntarlas será una tarea monumental.

Mi experiencia es que con una arquitectura clara, las dos piezas de este rompecabezas en particular pueden trabajar juntas en armonía. Al mantener el código generado aislado y sin cambios, aseguramos su protección para el futuro, ya que podemos regenerarlo y reemplazarlo en cualquier momento. El aislamiento también beneficia a nuestros seres humanos que pronto estarán encantados, que no se encontrarán con los bordes afilados del código escrito por una máquina.

En una capa separada para el usuario, podemos estructurar rápidamente esa interfaz de usuario ideal que teníamos en mente y luego agregar un código de "pegamento" liviano para llamar al back-end que maneja todos los detalles de integración.

A veces, esta configuración requerirá trabajo adicional para alinear las cosas para cubrir las peculiaridades de la API y proporcionar una experiencia de desarrollador de calidad . Cuando me enredo en esas secciones intensivas, pienso si prefiero resolver este complicado problema yo mismo o pedirle a cada desarrollador que lo solucione por sí mismo. Cuando lo pones así, me complace estar resolviendo este problema una vez, ahora mismo.

Cree SDK deliciosos

Una API robusta y consistente es un habilitador fuerte para las comunidades de desarrolladores, especialmente si está diseñada apropiadamente para la pila tecnológica y predecible en la forma en que se instala y opera. Un SDK es más que un conjunto de códigos de envoltura de llamadas a la API, en el que cada punto final funciona, pero es posible que no preste demasiada atención a las otras funciones de la misma biblioteca. Al adoptar un enfoque que proviene de ambos lados (integraciones precisas impulsadas por API en un lado y diseño de interfaz centrado en el usuario en el otro), creará SDK deliciosos que sus desarrolladores recomendarán a sus pares y volverán a consultar una y otra vez.

Publicar un comentario

0 Comentarios