Header Ads Widget

Ticker

6/recent/ticker-posts

El fin de la documentación de la API tal como la conocemos

 


Por un lado, tener la documentación de API adecuada puede ser una señal de éxito temprano para un proveedor de API, lo que permite a los nuevos usuarios comprender de manera efectiva las funcionalidades y advertencias detrás de una solución de API.

Por otro lado, una documentación extensa podría indicar una solución demasiado compleja con demasiadas variables para navegar. Incluso en aquellas situaciones en las que la documentación está totalmente justificada, por supuesto, a menudo puede ser una revisión más que cualquier otra cosa: el papeleo que excava cuando algo se rompe y no puede averiguar cómo hacer que la API haga lo que desea. .

No es así como tiene que ser. Como dijo Zane Claes de Airbnb durante su charla en la Cumbre de Plataformas de las APIs nórdicas 2016, Ninguna documentación es la mejor documentación.  Con este fin, muchos proveedores han comenzado a buscar nuevas soluciones para una mejor capacitación e información de los usuarios.

Hoy, vamos a discutir algunas de estas soluciones y lo que significan para el panorama de API. Discutiremos el sandboxing como un medio para incorporar usuarios y las diferencias entre documentación fluida y estática . Finalmente, veremos un caso de uso del mundo real para ver cuán poderosas pueden ser estas implementaciones. Si bien no se acerca el final de la documentación de la API, la forma en que la implementamos ciertamente está evolucionando.

El problema con la documentación

¿Qué es, específicamente, la documentación? En los términos más prácticos, la documentación es simplemente una colección de descriptores y demostraciones mediante las cuales un proveedor puede educar a un usuario sobre la funcionalidad de una API. Esto supone intrínsecamente lo siguiente:

  • El usuario no comprende, o no puede, inicialmente comprender las complejidades de la API interna, ya sea por complejidad u ofuscación;
  • Si una guía de error está presente fuera de los problemas de red estándar, la API puede manejar llamadas que resultarán en uno de estos errores; y,
  • La documentación será el punto principal (o uno de los puntos principales) para el apoyo continuo de la actividad del usuario.

La documentación en sí no es algo malo, por supuesto, pero tener documentación compleja, especialmente documentación estática compleja , asume que una o más de las condiciones anteriores son verdaderas. Después de todo, la persona promedio no lee el manual del usuario para la mayoría de los productos electrónicos de consumo, porque la funcionalidad se comprende fácilmente, y si lee el material, solo lo hace cuando se requiere la resolución de problemas.

La mayor parte de la documentación describe las complejas complejidades de la funcionalidad de la API de forma teórica . Son estáticos , rara vez cambian a menos que se implementen nuevas funciones. Incluso cuando se actualiza de forma rutinaria, la documentación es una solución conceptual que explica la funcionalidad sin permitir la experimentación.

Advertencia emptor: no toda la documentación se crea igual. Esta pieza no intenta pintar la imagen de la documentación como un gran mal; después de todo, la documentación es un pilar de la comunidad API. Sin embargo, lo que esta pieza intenta hacer es demostrar una mejor manera.

Sandboxing como documentación dinámica

Una de estas "mejores formas" es la idea de hacer documentación fluida, en lugar de estática, en forma de espacio aislado. El sandboxing en su forma básica consiste simplemente en crear un entorno controlado y conocido en el que los usuarios pueden probar llamadas y funciones con recursos conocidos.

Considere la diferencia entre "memorización" y verdadero "aprendizaje". Cuando un usuario tiene que recurrir a la memorización de la documentación o la referencia constante, se crea un problema en la ruptura entre el recurso y el acceso a ese recurso: el usuario depende completamente del recurso de incorporación en sí. Con el tiempo, el usuario estará cada vez más informado, pero la curva de principio a fin es extrema.

Sin embargo, cuando un usuario aprende, es increíblemente poderoso. El aprendizaje proviene de la experiencia : en lugar de hacer referencia a un manual de usuario, en una caja de arena, el usuario manipula los datos en tiempo real, experimentando con mutaciones y variaciones de una manera que realmente no se puede hacer con documentación simple.

Eso no quiere decir que el sandboxing esté reemplazando por completo la documentación , por supuesto; en esta solución en particular, la documentación debe estar vinculada al entorno de sandboxing de alguna manera. La creación de información sobre herramientas que muestre funcionalidades, la creación de una base de datos de funciones en la zona de pruebas que se pueda consultar, o incluso simplemente la creación de varias consultas de "prueba" predeterminadas y prefabricadas puede ser de gran ayuda para informar al usuario de lo que están haciendo.

Un maravilloso ejemplo de Sandboxing es GraphQL API Explorer de GitHub . Este sandbox de implementación GraphQL le permite probar la funcionalidad dentro del entorno sandbox y demuestra la facilidad con la que un usuario puede aprender a través de la interacción, en lugar de la memorización.

El sandboxing es una herramienta de apalancamiento. La documentación siempre estará disponible de una forma u otra, incluso con los problemas inherentes a la mayoría de las soluciones modernas, el hecho es que la documentación es necesaria para bases de usuarios e implementaciones efectivas.

Dado esto, ¿cómo utilizamos la documentación existente o planificada para el sandbox?

Implementación de Sandbox

Sandbox proporciona una forma de generar manipulaciones API interactivas.

Afortunadamente, el sandboxing está algo “de moda” últimamente, y debido a esto, hay una gran cantidad de soluciones novedosas y fáciles de implementar para crear rápidamente entornos simulados. Una de esas soluciones es Sandbox, que se llama acertadamente .

Sandbox es una solución de código abierto para generar automáticamente simulacros de API y servicios web RESTful o SOAP. Mediante el uso de definiciones de API para lo que denominan maquetas de API de “implementación instantánea, compilación colaborativa” (que es solo un nombre elegante para un banco de pruebas o sandbox), la solución permite a los desarrolladores impulsar nuevas revisiones y realizar pruebas rápidamente.

El atributo principal de Sandbox, sin embargo, es la idea de presentar una simulación controlada de la API en vivo al consumidor. Al utilizar herramientas inteligentes integradas en la solución (como respuestas dinámicas), el desarrollador puede guiar a un nuevo usuario en lugar de arrojarlo al proverbial extremo profundo.

Sandbox se extrae directamente de la documentación de la API (específicamente Apiary, Swagger, Readme.io, RAML, Gelato, WDSL y Stoplight) para su autogeneración, lo que lo hace muy atractivo para los desarrolladores a largo plazo que desean una solución de sandbox, ya que elimina gran parte de la barrera de entrada y reemplaza esa barrera con automatización.

Lo más importante (para algunos): esta solución es completamente de código abierto , lo que hace que confiar en ella para manejar incluso API seguras sea una propuesta mucho más segura.

La clave aquí es crear un entorno en el que el usuario pueda experimentar y aprender, en lugar de simplemente memorizar. Pero, ¿es el sandboxing la única solución a este problema?

Explore también los beneficios del uso de pruebas automáticas para la documentación de API

Explorar como aprender

Aprendemos a través de la experiencia .

La manipulación a través del espacio aislado es solo un enfoque. Otra fuente de aprendizaje es la idea de exploración . Mientras que el sandboxing se basa en que el usuario manipule e interactúe con una simulación en vivo y auto-incluida de la API, las soluciones exploratorias, por el contrario, se enfocan en hacer que la API y todas sus partes estén más abiertas para arrancar.

Al explorar las construcciones relacionales que impulsan una API y ver cómo cada elemento se vincula con otro a través de llamadas y mutaciones, el usuario puede obtener una comprensión de "nivel superior" de los datos disponibles, cómo se procesan y cómo interactuar con el sistema. de una manera beneficiosa.

Sin embargo, al igual que con el sandboxing, la exploración es simplemente un enfoque diferente para presentar la documentación. La exploración corrige la documentación estática no a través de una capa de ofuscación como en el sandboxing, sino guiando cómo se presenta al usuario la información que consume: el contenido se presenta de la manera en que el autor desea que se presente, específicamente en la forma exacta en que se presentó. codificado (con todo el razonamiento implícito dentro).

Implementación de exploración

La consola GraphiQL es un ejemplo de aprendizaje de API exploratorio.

Una solución más exploratoria para la documentación de API es el explorador de API GraphiQL . GraphQL es un potente lenguaje de consulta creado por Facebook. Su poder principal radica en el hecho de que crea una comunidad entre el cliente y el servidor, y permite la obtención y manipulación de datos de una manera mucho más ágil y eficiente.

GraphiQL se basa en esta conceptualización relacional para presentar las API GraphQL de una manera consumible y comprensible. Uno de los mejores beneficios de cómo GraphiQL hace esto es el hecho de que la información sobre herramientas y otra información se integran de forma nativa, en lugar de agregarse posteriormente como en las soluciones de espacio aislado.

GraphiQL genera un “panel” en la vista exploratoria, vinculando recursos a las funciones que interactúan con ellos y brindando información en tiempo real sobre la naturaleza de los datos con los que se interactúa. Esto también se extiende a la codificación y manipulación iniciales, evitando que se generen errores y brindando sugerencias y consejos útiles a medida que el usuario continúa a través del panel.

Un gran beneficio de este enfoque es la viralidad de la exploración generada: GraphiQL guarda sesiones y puede compartirlas con otros para mostrar errores, demostrar soluciones efectivas e incluso implementar nuevas soluciones teóricas para problemas de larga data.

Esto es marcadamente diferente del sandboxing, que a menudo es una perspectiva de "navegar y borrar", donde el trabajo realizado en un sandbox se borra cuando el usuario sale de la ventana o aplicación. Debido a esto, GraphiQL es algo más adecuado para el aprendizaje exploratorio a largo plazo , mientras que el sandboxing es algo más adecuado para la experimentación en el lugar y ejemplos de documentación preexistente.

Relacionado: 10 consolas GraphQL en acción

Documentación fluida frente a estática

Si bien estos dos métodos son diferentes en muchos aspectos, plantean una pregunta filosófica básica que el espacio de la API debe responder: ¿realmente necesitamos (o queremos) documentación fluida? Y más concretamente, ¿vale la pena la documentación fluida?

De lo que estamos hablando aquí es una cuestión de variabilidad. La documentación estática es solo eso: inmutable a menos que se presente como una gran actualización, un bastión constante de información tan confiable como la salida del sol por la mañana, en un inglés simple y sencillo. No hay interfaces sofisticadas, ni entornos sandbox complejos, solo una simple documentación de "causa y efecto".

La documentación fluida , por otro lado, está en marcado contraste, en constante evolución, saliendo del Léame o sitio wiki estándar de GitHub y entrando en el mundo del sandboxing y las soluciones de exploración variable. Las llamadas tienen respuestas variables, entonces, ¿por qué deberían estar representadas por contenido estático? La documentación fluida dice "no debería" y prefiere presentar los datos de manera relacional en lugar de simplemente decir "si esto, entonces aquello".

Entonces, ¿cuál es el problema, entonces? ¿Es realmente una diferencia tan simple?

Por supuesto, existe el problema de la autoridad. Cuando un usuario interactúa con la documentación, lo que está haciendo es buscar información, y hay algo que decir sobre la documentación estática en este ámbito: cuando los datos no cambian y se presentan en un formato fácil de leer, el aprendizaje está estandarizado . Cada usuario aprende lo mismo, de la misma manera, y por lo tanto es una entidad predecible y compatible.

Y luego está el problema con la integridad de los datos. Cuando los datos se cambian constantemente, especialmente en la documentación, los usuarios pueden terminar pensando que su variación es el método verdadero y renunciando al método "nuevo" presentado en la documentación dinámica.

Finalmente, existe preocupación por la privacidad . Para que una API segura se beneficie de la exploración o el sandboxing, el proveedor debe asegurarse de que las consultas interactivas no llamen a funciones que de otro modo podrían estar prohibidas para ciertos usuarios.

La verdad es que, incluso con todas estas fallas, las soluciones dinámicas siguen siendo las mejores, siempre que se les dé el espacio adecuado para funcionar. El mejor enfoque es uno de dos niveles : los proveedores siempre deben proporcionar documentación estática para la carne ”de la API , mientras usan una caja de arena como el mecanismo de incorporación del usuario frontal .

Al respaldar este enfoque de dos carriles, puede obtener lo mejor de ambos mundos: recibe los beneficios de usabilidad de un esquema de incorporación con datos dinámicos, junto con la confiabilidad de la documentación estática.

Lea también: Virtualización, Sandboxes y Playgrounds para una API saludable

Pensamientos finales

Al igual que con cualquier tecnología o solución en el espacio de API, existen muchas variaciones en cuanto a cómo se pueden implementar estos dos principios. El simple hecho es que unir documentación estática y dinámica es más poderoso que cualquier componente por sí solo y es infinitamente más útil para el usuario promedio.

La unión de estas dos soluciones no solo da como resultado un aprendizaje más efectivo, sino que también resulta en una incorporación más efectiva de los usuarios potenciales desde ambos ángulos, lo que le permite optimizar su servicio para aquellos que prefieren leer para aprender y los usuarios que prefieren la experimentación activa.

Lo más importante es que estas dos soluciones no se excluyen mutuamente: un desarrollador puede, si así lo desea, implementarlas una al lado de la otra, aprovechando las fortalezas de cada una para cubrir las debilidades de los demás. Esa es la belleza de este enfoque: es completamente extensible y modificable, y con esa personalización, extremadamente poderoso.

Publicar un comentario

0 Comentarios