Header Ads Widget

Ticker

6/recent/ticker-posts

3 métodos para documentar los servicios API JSON


 JSON es un formato estándar abierto muy potente que utilizan muchos servicios y API en Internet. Desafortunadamente, aunque el estándar abierto conlleva muchas ventajas, también crea algunos errores que los desarrolladores pueden no estar preparados para manejar.

Uno de estos escollos es que, en combinación con su uso generalizado, la naturaleza de código abierto conduce a la fragmentación en la forma en que se documentan los servicios de API JSON . No existe un método de documentación "estándar".

Afortunadamente, sin embargo, existen algunas buenas soluciones para la documentación JSON que representan la mejor de todas las palabras cuando se trata de este formato. Hoy, analizaremos estas soluciones, así como lo que significan para su documentación en su conjunto.

¿Qué es JSON?

JSON (notación de objetos JavaScript)

JSON (notación de objetos JavaScript)

JSON, o JavaScript Object Notation, es un esquema de codificación liviano y altamente eficiente que se deriva de XML como respuesta a las crecientes demandas de comunicación entre el servidor y el navegador. En ese momento, a principios de la década de 2000, las únicas soluciones reales para las demandas cada vez mayores de nuevos métodos de entrega en la naciente web hipermedia rica en medios eran subprogramas de terceros, típicamente Flash o Java, que agregaban un peso innecesario y una barrera de entrada. para muchos consumidores.

JSON fue una evolución natural de Javascript , aunque la especificación no se comprometió formalmente hasta mucho más tarde bajo RFC 4627 - por esta razón, el "creador" Douglas Crockford ha declarado que "descubrió" JSON en lugar de crearlo.

El principal atractivo de JSON es el hecho de que tiene una sobrecarga de ancho de banda más baja, lo que lo hace muy atractivo para aplicaciones de alto volumen de llamadas o aquellos sistemas que utilizan fragmentos de datos de gran tamaño. Por ejemplo, el siguiente es un intercambio de credenciales estructurado XML:


    admin
    default

El mismo intercambio de credenciales expresado en un fragmento JSON condensado válido se ve así:

{"credential":[
{"username":"admin", "password":"default"} ]}

Si bien en el nivel superficial no parece haber mucha diferencia entre los dos (y de hecho, parte de la popularidad detrás de JSON es que es casi completamente intercambiable con XML), la diferencia de tamaño extrapolada sobre miles de líneas de código es una gran diferencia .

Más concretamente, JSON es mucho más legible de lo que XML podría esperar en su configuración nativa. Tomemos otro ejemplo, esta vez para un depósito de artículos, con una sola entrada extraída.

Primero en XML:



   3 Ways to Document JSON API Services
   Kristopher Sandoval
   
      Nordic APIs
      2016
      

Si bien podemos ver un poco el contenido, está oscurecido por una estructura arcaica y personajes extraños. Esta misma función en JSON se ve bastante mejor:

{
"blogpost": 123, "title": "3 Ways to Document JSON API Services" "author": "Kristopher Sandoval", "published": { "publisher": "Nordic APIs", "year": 2016, }
}

El segundo ejemplo es más corto y mucho más agradable a la vista en general: es un formato legible por humanos , en lugar de legible por máquina . Si bien se podría argumentar que XML es en esencia un lenguaje en lugar de un formato de datos, cuando el argumento entre XML y JSON se discute a menudo, no está dentro del contexto del uso de XML como lenguaje, más bien como un formato de datos - el El mundo de las API, en muchos sentidos, se ha alejado de XML hacia otras alternativas, por lo que el argumento es quizás menos válido de lo que era a principios de la década del 2000 cuando JSON fue "descubierto" por primera vez.

Ahora sabemos qué es JSON y por qué se usa tanto. Pero, como JSON es un estándar ampliamente adoptado en un arreglo de código abierto, no existe una autoridad única para su documentación.

Los desarrolladores han adoptado una amplia gama de prácticas de documentación para los servicios JSON (y, en general, las API que responden en formato JSON), cada una con sus propios aspectos negativos y beneficios. Los usuarios pueden estar familiarizados con este tipo de problema con Linux: un único núcleo de código abierto segmentado en cientos de variaciones, cada una con su propia variación en la documentación y el formato.

Si bien esto es negativo en algunos aspectos, en otros también es un atributo positivo: ninguna autoridad que impulse un enfoque de documentación centralizada significa que los desarrolladores tienen una gran variedad en su metodología, y realmente es un "mercado de elección" en términos de soluciones.

Si bien ciertamente ha habido un impulso hacia un enfoque centralizado con esfuerzos como el proyecto Open API Specification , esa no es una verdadera centralización en la forma en que, digamos, Swagger tiene una autoridad centralizada para su especificación y detalle. Por su propia naturaleza, se podría argumentar que una autoridad centralizada sería difícil de establecer y hacer cumplir.

Relacionado: La forma más fácil de generar documentación de API

Utilice una solución de documentación de terceros

Soluciones de terceros para

Como siempre ocurre en el espacio tecnológico, donde hay un problema, hay un grupo de empresas dispuestas a venderle una solución . Algunos son más fuertes que otros, pero todos funcionan según el principio básico de traducir la estructura subyacente de su API en una documentación comprensible y extensible , que es exactamente lo que estamos buscando.

Las soluciones como Mashery I / O Docs son excelentes en este caso de uso particular, ya que usan específicamente un esquema JSON para describir la API, sus recursos, métodos, parámetros y funciones. Siempre será más fácil y efectivo documentar el contenido en el mismo idioma o sintaxis que el contenido en sí. Imagine intentar leer un diccionario de español escrito en mandarín y verá por qué esto es importante.

Por supuesto, no tiene que ceñirse al esquema JSON. Las soluciones como la herramienta Dexy tienen un propósito más general , admiten una amplia gama de idiomas y generan documentación en una variedad de esquemas seleccionados. Esto puede funcionar mejor en situaciones en las que la funcionalidad JSON que se está documentando tendrá que trasladarse a otro formato de datos o interactuar con él en un entorno heredado que aún utiliza XML.

Un gran beneficio de este enfoque es el hecho de que las soluciones de terceros a menudo tienen un conjunto de características más completo que puede hacer que su adopción sea más valiosa. Soluciones como Readme.io permiten el trabajo colaborativo, el soporte de versiones y los foros de soporte integrados en la solución como un todo, lo que hace que la documentación sea una pequeña faceta de una solución más grande.

Estas soluciones, por supuesto, agregan valor debido al hecho de que no se utilizó tiempo de desarrollo para implementarlas. Esto es ahorro de costos , ahorro de tiempo y ahorro de esfuerzo, lo cual es increíblemente poderoso.

Independientemente de la solución que se implemente, lo importante es que el contenido se describa de tal manera que pueda replicarse en la base del código. Proporcionar ejemplos , demostraciones en vivo y recursos de producción también es una combinación eficaz para la documentación.

Por lo tanto, en la mayoría de los casos (con uno de esos casos demostrado anteriormente en este texto), las soluciones de terceros que se adhieren al esquema JSON serán la mejor opción del desarrollador promedio para documentar estos servicios.

El problema aquí es que depende de un recurso externo, pasando su código a través de plataformas y dispositivos de documentación externos. Esto está bien para soluciones de propósito general y con compañías confiables, pero para una API privada más segura que  albergue secretos comerciales, esta no es una opción adecuada.

También:  Tutorial con el modelo de API para la generación de documentación

Derivar del marco

Derivar la documentación del marco

Si bien una solución de documentación de terceros siempre está sobre la mesa, los desarrolladores pueden reducir su dolor de cabeza desde el principio desarrollando dentro de un marco específico que proporciona documentación automática o semiautomática a medida que se desarrolla la API.

En general, estos pueden considerarse "terceros" en el sentido de que estos marcos se desarrollan externamente; Dicho esto, el código subyacente es completamente interno y, por lo tanto, esta solución ocupa un ámbito de segunda parte o de empresa a empresa.

Tomemos, por ejemplo, el siempre popular Swagger , que funciona como marco y como especificación. Al desarrollar dentro de un marco específico, los usuarios de Swagger pueden implementar un sistema que puede documentar la producción, el consumo y la estructura subyacente de un servicio RESTful . Más concretamente, Swagger es independiente del lenguaje, lo que significa que a menudo se adapta perfectamente a sistemas multilingües o complejos que generan en un formato de datos específico, como los que a menudo se basan en JSON.

Otras soluciones como ASP.NET API Explorer utilizan su propio formato de código para generar automáticamente documentación efectiva. Esto es diferente de una solución de terceros en que funcionalmente es su propio código haciendo referencia a sí mismo. El Explorador de API es fundamentalmente una capa de abstracción y utiliza el enrutamiento y la exploración de ramificación para documentar la funcionalidad de una API, que no solo es excelente para fines de documentación, sino también para pruebas de errores y descubrimiento de duplicaciones.

Por supuesto, todo esto depende de la idea de que ha creado una API sólida. Si tiene errores y problemas dentro del código en sí, este tipo de generación automática desde el marco parece estar muy bien, pero en realidad puede ayudar a ocultar algunos de estos errores, ya que no están tan claros como lo estarían en ninguno de los dos. documentación manual o en soluciones de terceros, donde la verificación de errores a menudo se incluye en el sistema en cuestión.

Crear un depositario manual

Repositorio manual

Finalmente, está el enfoque manual . Esto a menudo requiere marcar a mano o agregar rebajas a sus funciones para generar documentación de manera efectiva. Si bien las soluciones basadas en marcos y de terceros podrían implementarse después del hecho, es mejor planificar la creación de un depósito manual con mucha anticipación a la construcción de la API.

Tomemos, por ejemplo, la solución de Apiary.io . Este servicio genera planos de API utilizando rebajas especializadas, devolviendo contenido simple, legible y comprensible. Por ejemplo, para documentar una función simple, antes de la función en sí, agregaría lo siguiente.

# Article call - calls the article in question with all attached data types

Sin embargo, este tipo de documentación no requiere recursos externos; el equipo de desarrollo puede lograr gran parte de ella física y manualmente de la misma manera, pero con un mayor costo de tiempo . La creación de una wiki o base de conocimientos es una metodología práctica para generar documentación personalizada, pero requiere mucho tiempo.

Reducción

Reducción

El punto principal aquí es mostrar las funciones de cada llamada y el contenido esperado; si bien esto es fácil de hacer al principio de las etapas de planificación, la gran desventaja de este tipo de documentación es que generalmente no es muy adaptable (a menos que se use un enfoque de marcado como con Apiary.io). Para proyectos más pequeños, esto no es gran cosa; para proyectos colaborativos donde una característica puede pasar por diez iteraciones antes de la producción, esto podría ser un factor decisivo.

Sin embargo, todas estas soluciones se reducen a una adopción temprana , ya que la adición retroactiva de marcado a todas las funciones y llamadas puede no ser la opción más económica dado el tamaño y la cantidad de contenido que se etiqueta. La compensación es que, si bien la sobrecarga inicial es alta, usted tiene una supervisión completa y sin restricciones sobre cómo se documenta su API y cómo se describe cada función.

Eso en sí mismo podría ser lo suficientemente valioso como para renunciar a cualquier reparo sobre el costo de tiempo involucrado.

Conclusión: considere la escalabilidad

A lo que se reduce toda esta conversación es a esto: como ocurre con muchas cosas en la vida, su elección se basa en la naturaleza del sistema en cuestión. Una API en sus inicios puede salirse con la suya con la documentación manual y las sintaxis de marcado con bastante facilidad, ya que el costo inicial es algo bajo, especialmente en API y sistemas más pequeños.

Sin embargo, a medida que avance, se encontrará en una situación en la que la documentación manual lleva casi tanto tiempo como la codificación. Si bien el marcado resuelve esto de alguna manera, aún está obligado a documentar cada cambio, matiz y concepto en detalle.

Las soluciones marco son muy efectivas, pero dependen de la adopción de un marco. Esta adopción significa que está atado a un ecosistema que puede o no tener soporte y revisión a largo plazo. Esto significa que el tiempo que se ahorra en los estados iniciales se perderá en la migración a un nuevo marco o sistema.

Por último, las soluciones de terceros son excelentes y funcionan para el 99% de los casos; sin embargo, exponen su base de código a un tercero y dependen de los desarrolladores de esa solución en particular.

Cada uno de estos enfoques tiene sus matices, y la elección entre ellos descansa firmemente en las condiciones que puede soportar el sistema dado.

Publicar un comentario

0 Comentarios