Header Ads Widget

Ticker

6/recent/ticker-posts

7 elementos sin la documentación de API

Las API web son elementos muy variables: pueden crearse a medida, diseñarse en torno a un único propósito, abarcar todo y casi todo lo demás. Los requisitos cambiantes dictan de qué se compone la interfaz. Debido a esto, es difícil encontrar puntos en común entre las API y sus portales orientados al usuario.

Dicho esto, existen algunos requisitos básicos que, a pesar de la variabilidad de la industria de las API, todas las API deben cumplir si alguna vez quieren tener una base de usuarios.

Independientemente de la función o el propósito de la API, hay siete elementos básicos que toda API web debe tener en su documentación . No incluir ninguna de estas características podría tener efectos drásticamente negativos en la adopción, comprensión y usabilidad.

Hoy, analizaremos estos siete elementos básicos y definiremos exactamente qué son, por qué los necesita y cómo agregan valor a la API.

1: un esquema de autenticación

La autenticación, en pocas palabras, es demostrar que eres quien dices ser. Esto a menudo se confunde con la autorización o el acto de demostrar que se le permite hacer lo que está solicitando, pero en última instancia, la autenticación es un medio de "iniciar sesión" en la interfaz. La autenticación es clave para muchos sistemas que manejan la administración de derechos.

Eso no quiere decir que su sistema de autenticación tenga que ser particularmente robusto o complejo, hay una amplia gama de mecanismos de autenticación. Como ejemplo, la autenticación básica HTTP es quizás uno de los métodos más fáciles de implementar en una API. Hacer cumplir el control de acceso utilizando este método simplemente incorpora un encabezado de autorización en cada solicitud y pasa una combinación de nombre de usuario y contraseña al sistema de autenticación para demostrar que el usuario es quien dice ser.

El uso de algo como un JWT o JSON Web Token puede proporcionar no solo autenticación, sino también una firma segura que a menudo se pasa como un paquete completamente codificado. Este paquete se puede cifrar fácilmente con algo como JOSE, o la biblioteca de cifrado y firma de objetos JSON, para crear una metodología segura.

Hay varios métodos de autenticación que van desde simples a complejos, cada uno con sus propias metodologías, excentricidades y advertencias. No documentar su método de autenticación de manera clara y sencilla no solo hará que el descubrimiento de la función de la API sea mucho más difícil, sino que también puede hacer que los usuarios por primera vez opten por no usar la API en absoluto, eliminando su base de usuarios inicial. Documente su método de autenticación, cualquiera que sea, ¡y hágalo completamente!

Relacionado: Guía definitiva para tres tipos de autenticación de API (autenticación básica, claves de API, OAuth

2: Definiciones del tipo de llamada HTTP

Quizás tan fundamental como señalar el esquema de autenticación elegido es la documentación detrás de los distintos tipos de llamadas HTTP . Cualquier API web interactuará con los diversos métodos de llamada HTTP y, como tal, documentar qué métodos se usan y cómo se usan dentro de su API será extremadamente importante.

La verborrea común del tipo de llamada que debe definirse y discutirse se enumera a continuación.

  • GET : normalmente utilizado para recuperar una representación de un recurso, GET será uno de los verbos más utilizados para la mayoría de las API. Como tal, la documentación debe profundizar en exactamente para qué se usa GET en la API, qué recursos se pueden llamar y qué limitaciones existen en esta funcionalidad.
  • POST : menos comúnmente utilizado por el usuario promedio que GET, POST es un método para enviar una entidad al recurso y, por lo general, resulta en un cambio de estado. POST todavía se usa comúnmente y, como tal, debe considerarse secundario en importancia a GET, pero tratado con la importancia que merece.
  • PUT : PUT es esencialmente un método para actualizar o reemplazar una entrada. En consecuencia, esta función estará realmente limitada a los usuarios autorizados en la mayoría de las implementaciones y, como tal, puede que no sea aplicable a toda la base de usuarios. Dicho esto, se debe documentar bien cómo funciona PUT y qué entradas se pueden cambiar.
  • PATCH : se usa para actualizar o modificar una entrada, PATCH estará igualmente limitado como PUT, aunque en algunas implementaciones podría usarse para modificar entradas específicas que son únicas para el usuario; en este caso, la documentación sobre cómo se hace debe diferenciar entre los dos.
  • ELIMINAR : Eliminar se usa específicamente para eliminar una entrada y, como tal, a menudo tiene un uso muy limitado y requiere mayores derechos para su uso. En consecuencia, si bien el uso de DELETE puede no ser algo que deba documentarse ampliamente, las limitaciones de las clases de usuario definitivamente deben hacer referencia a esta palabrería y si es algo de lo que el usuario promedio tendrá que preocuparse o no.
Lea también: No infrautilice estas 5 increíbles funciones de rendimiento HTTP

3: Definiciones de puntos finales

Todo lo que se ha documentado, por supuesto, es completamente inútil sin explicar los puntos finales específicos que se utilizarán. Los puntos finales se nombran con cierto humor, considerando que son el comienzo de la interacción del usuario con su sistema interno; en consecuencia, deben documentarse con el peso adecuado.

Como ejemplo, supongamos que tenemos un punto final como ¿Qué hace específicamente ese punto final? Con solo decir que existe, no hemos hecho casi nada: no hemos discutido qué hace el punto final, cuáles son sus limitaciones, si tiene algún punto final asociado o hermano que pueda usarse como un canal alternativo, o incluso si ese punto final está restringido a usuarios específicos.https://api.nordicapis.com/v1/

La primera forma en que podemos comenzar a agregar valor a esta definición de punto final es explicar específicamente qué hace y cómo se relaciona con otros puntos finales. Crear un mapa de puntos finales y explicar su función y forma dentro de la propia API es clave para este elemento de documentación. No solo ayudará a su usuario a comprender el sistema a un mayor nivel, en teoría, también puede ayudar en general en el desarrollo al permitirle contextualizar la función holística del sistema como un todo, tanto desde el punto de vista del desarrollador como del usuario.

4: Estructuras, métodos y parámetros de URI

Para agregar aún más valor a esta definición de punto final, debemos documentar la estructura y los métodos para cada URI dentro de la API. Esto debería hacerse a un nivel tan profundo que el usuario medio debería tener todas las funciones a su disposición descritas, en detalle, para facilitar su uso. Dicho esto, no todo lo relacionado con un punto final puede o debe documentarse, especialmente si el usuario promedio no tiene los derechos que podrían ser necesarios para usarlos.

Por ejemplo, no es raro tener API segmentadas en dos grupos generales: una versión gratuita (o incluso limitada en el tiempo) de la API y una que es estrictamente para usuarios de empresa a empresa o monetizados . En este caso, puede haber funciones en la API reservadas para un pequeño subconjunto de usuarios. La documentación de dicho punto final solo debe proporcionarse al usuario que tiene la autorización para usarlo. La exposición de información a las partes equivocadas podría resultar en exploits o ataques .

Cuando se trata de documentación funcional, lo que a menudo se pierde es el hecho de que los desarrolladores irán descubriendo la API poco a poco, a medida que se descubren o se requieren funciones. Esto crea una dicotomía en la que el proveedor ve una función como obvia, pero el usuario desarrollador puede verla como ofuscada; con este fin, el host de la API debe documentar no solo los métodos de sus URI, sino también los parámetros que podrían aceptar. Estos métodos y parámetros deben estar bien documentados , explicando exactamente lo que hacen cada uno y cómo hacen lo que hacen, limitados solo por lo que el desarrollador cree que el usuario debería tener acceso por razones de seguridad.

5: Descripciones de métodos legibles por humanos

La idea de incluir descripciones legibles por humanos es menos un punto técnico y más centrado en el ser humano . Si bien los datos que sugerimos anteriormente son realmente importantes, no todos los usuarios de su API podrán comprenderlos en su forma simple. Debido a esto, la adopción de su documentación legible por máquina en sistemas personalizados legibles por humanos es extremadamente importante.

Esto, de hecho, presenta una oportunidad para reevaluar cuál es realmente el propósito de nuestra documentación. Hasta ahora, solo hemos discutido la documentación en términos de lo que necesitará el usuario final técnico.

Si bien esto está bien en términos generales, pasa por alto el hecho de que no todos los usuarios van a ser muy técnicos; como tal, debemos considerar la documentación como menos un "manual técnico" y más como un "tomo de comprensión". Definir sus métodos y entidades de documentación en términos humanos es extremadamente importante como complemento de la documentación más técnica.

Relacionado: Diseño de API para humanos

6: Solicitudes y ejemplos

Conocer una estructura de URI es importante, sí, pero en última instancia, sin una idea de cómo se ve la solicitud de URI en la práctica , esta documentación está completamente incompleta. En consecuencia, una serie de ejemplos de cómo se ve una solicitud efectiva sirve para algunos propósitos clave.

En primer lugar, actúa como un final para el resto de su documentación técnica; mostrando ejemplos de llamadas a API convierten los datos técnicos en información procesable.

En segundo lugar, esto sirve como un método clave para la incorporación de usuarios Ninguna cantidad de datos es útil sin poder ponerla en práctica, y aunque la mayoría de los usuarios entenderán las solicitudes simples, las solicitudes detalladas y complejas merecen su propio tipo de cuasi-tutorial. En consecuencia, esto puede cumplir esa función bastante bien.

Finalmente, proporcionar ejemplos puede ayudar en el proceso de resolución de errores , ya que los usuarios pueden ver sus solicitudes fallidas y compararlas con lo que debería ser la solicitud. Esto les ayudará a identificar problemas en sus solicitudes y su enfoque general, lo que les permitirá resolver su problema con una dependencia mínima de los canales de soporte de API . También debe tenerse en cuenta que las solicitudes de ejemplo idealmente deberían mostrar una variedad de idiomas compatibles .

Un gran ejemplo de este tipo de documentación se puede encontrar en el Centro de desarrollo de Heroku . Heroku ofrece documentación en Node.js, Ruby, Java, PHP, Python, Go, Scala y Clojure. Al ofrecer esta amplia gama de opciones de documentación, no solo cubren lenguajes populares, sino también lenguajes que tienen un uso más limitado o para tipos específicos de sistemas (como Go , que normalmente se usa para aplicaciones de alta concurrencia que requieren una base de código relativamente simple ).

Cómo: las formas más fáciles de generar documentación de API

7: Respuestas esperadas

Un elemento de la documentación de la API que a menudo se pasa por alto, la documentación de la respuesta esperada es extremadamente importante. Cuando un usuario realiza una solicitud, la respuesta, incluso si tiene éxito, a menudo puede estar envuelta en una serie de funciones, un paquete específico del idioma u otro tipo de envoltorio de datos. Esto puede hacer que las respuestas reales de la API sean difíciles de descifrar. Es muy importante poder esperar una respuesta determinada, en un idioma determinado y con un formato determinado.

Tenga en cuenta que, en algunos casos, esto es menos importante; para GraphQL , por ejemplo, gran parte de la respuesta está realmente definida por la solicitud, por lo que un ejemplo de respuesta general es más apropiado. Sin embargo, incluso entonces, la documentación de códigos de error comunes , notas de éxito comunes y la estructura y formato esperado de dicha respuesta es extremadamente valiosa para el usuario final y no debe ignorarse.

Soluciones de documentación de cocina casera vs API. ¿Cual es mejor?

Si bien los elementos discutidos anteriormente son ciertamente difíciles de argumentar, cómo se genera la documentación de la API es en realidad un tema muy debatido. Hay tantos métodos de generación de documentación como API que pueden utilizar dichos métodos y, como tal, es bastante difícil dar una única recomendación por encima de todas las demás.

Dicho esto, normalmente se clasifican en dos campos: implementaciones caseras de bricolaje o soluciones de documentación , sistemas que crean documentación automáticamente utilizando un conjunto de criterios. Ambos tienen sus propios valores y propiedades, pero en última instancia, la elección se reduce al propósito específico de la documentación.

Documentación casera

Cocido en casa, o bricolaje, significa que los desarrolladores anotan las funciones a mano. Con suerte, esto se hace de manera deliberada y pensando en la editabilidad de dichos recursos en el futuro. Los métodos populares para hacer esto pueden variar desde un simple sitio web estático que presenta documentación de API hasta una ** wiki rica en hipermedia **, que permite la edición de la comunidad, el seguimiento de errores y más.

Si bien estos sistemas ofrecen una flexibilidad y control sin precedentes, y se implementan fácilmente en proyectos existentes, requieren una cantidad significativa de esfuerzo y energía para mantener y, a menudo, requieren un miembro del equipo cuyo propósito principal en el equipo es servir como gerente de documentación. Para proyectos pequeños, este es un costo difícil de justificar.

Sistemas automatizados

Para las API que desean tener un sistema más automatizado desde la documentación hasta la iteración, hay muchas herramientas disponibles, como Swagger UI, Slate, Gelato y más. En una publicación anterior , investigamos y trazamos más de 30 soluciones de documentación de API. Existen muchas opciones, desde herramientas prácticas de código abierto hasta portales completos para desarrolladores. Muchas de estas bibliotecas y marcos se pueden usar para generar HTML y CSS para mostrar métodos API, parámetros, valores, solicitudes, respuestas, ejemplos de código y más.

Leer: Guía definitiva para más de 30 soluciones de documentación de API

Un gran DX requiere documentación más que eficaz

Si bien es tentador considerar la documentación como una ocurrencia tardía, el simple hecho es que es probable que dicha documentación sea el primer punto de entrada a su API y los sistemas que la impulsan para el usuario promedio. En consecuencia, proporcionar documentación eficaz debe considerarse menos una ocurrencia tardía y más como un dato importante y crítico para el usuario promedio.

Los elementos discutidos a lo largo de este artículo forman la base para una interacción del usuario poderosa, efectiva y positiva. Sin embargo, el simple hecho de tener documentación eficaz no garantiza una buena experiencia de usuario o una comunidad de desarrolladores. Otras áreas de mejora incluyen una zona de pruebas de pruebas, canales de soporte para desarrolladores y garantizar un alto tiempo de actividad con rigurosas pruebas internas de API.

En última instancia, su documentación, como se dijo anteriormente, es una base: cuanto más fuerte sea su base, más grande puede ser la estructura. Una base perfecta no crea una mansión de la noche a la mañana. En otras palabras, mantenga la perspectiva de lo que está construyendo y aborde estos elementos a medida que surjan.

 

Publicar un comentario

0 Comentarios