Header Ads Widget

Ticker

6/recent/ticker-posts

Utilice las pruebas automáticas de documentación de API para impulsar el crecimiento de API


 Es una verdad universal que probar los errores y depurar los que aparecen no es un proceso divertido.

Casi todos los proveedores de API están familiarizados con el proceso de monitoreo y prueba. Antes de enviar el código, los comportamientos de la API deben examinarse minuciosamente, como ocurre con cualquier versión de software.

Entonces, ¿por qué, cuando se trata de documentación de API , muchas personas adoptan la postura de "configúrelo y olvídelo"? Con demasiada frecuencia, los propietarios de API escriben documentación estática, la publican en su centro de desarrolladores y nunca la vuelven a tocar.

Según Rouven Weßling de Contentful, quien habló sobre la automatización de las pruebas de documentación de API en nuestra Cumbre de plataforma 2016, los propietarios de API deben poner más énfasis en mantener su documentación actualizada. y coherente con su comportamiento de API, ya que los usuarios desarrolladores “preferirían no tener documentación , o documentación incompleta, que documentación incorrecta ".

En otras palabras, cualquier propietario de API que proporcione documentación defectuosa corre el riesgo de enfurecer a los usuarios hasta el punto de que puedan abandonar la API por completo siempre que encuentren una alternativa viable. Para evitar eso, debemos asegurarnos de que las pruebas de documentación de API se conviertan en la norma.

Afortunadamente, para evitar dolores de cabeza, existen herramientas que pueden automatizar una buena parte de este proceso. Entonces, dentro de este artículo, brindaremos una descripción general de alto nivel sobre el uso de API Blueprint , Dredd y Travis CI para realizar pruebas continuas de documentación de API.

Vea a Rouven Weßling presente en las API nórdicas:

Prueba de la documentación de API 101

Hemos escrito extensamente sobre por qué es tan importante proporcionar documentación completa de la API , y las razones deberían ser bastante obvias:

  • Puede proporcionar una guía rápida y sencilla para comenzar con su API.
  • Demuestra funciones útiles
  • Es la cara frontal de su programa de desarrolladores y actúa como un punto de venta para adquirir nuevos desarrolladores.
  • Ayuda a reducir la frustración del usuario

Pero la documentación de la API solo puede realizar estas funciones si es concisa, útil y precisa. Mientras que las pruebas regulares no pueden ayudar con el aspecto sucinta - la prueba será ayudar a asegurar que la documentación es técnicamente exacta y actualizada. Aunque no es una receta mágica para convertirlo en una documentación excelente y sorprendente, definitivamente puede ayudar a mejorar la precisión.

La primera forma de hacerlo es adoptar la estandarización . La elaboración de documentación legible por humanos implica un cierto toque personal, sin embargo, si está anotando documentación manualmente, puede ser difícil automatizar las pruebas si hay elementos de subjetividad.

La respuesta de Weßling a esto es utilizar una especificación API :

“Si desea probar su documentación, realmente necesita basarla en una especificación. No hay forma de simplemente probar la prosa que escribes; debe tener un formato bien definido para realizar la prueba ".

El uso de API Blueprint ciertamente podría funcionar, pero otros formatos de especificación populares también funcionan: Swagger / Open API Specification y RAML . Como en muchos casos, se trata menos de la herramienta que utiliza, sino de la medida que toma para facilitar el proceso de prueba de la documentación.

Para generar documentos, consulte: Guía definitiva para más de 30 soluciones de documentación de API

Configurar enlaces para probar todas las transacciones de API

Como señala Weßling, probar funciones de solo lectura mediante GETsolicitudes no le brinda toda la historia. Para probar las complejas interacciones de toda su API, recomienda comenzar a experimentar con hooks .

Aquí es donde Dredd entra en acción. Dredd actúa como un CLI para la validación de que la documentación de la API y la implementación real se sincronizan arriba. Usados ​​en este contexto, los ganchos le permiten ejecutar código en cada paso de la prueba y anular ciertas cosas en el ciclo de vida de una prueba individual. A continuación, se muestran algunos ejemplos de cómo se ven:

  • beforeAll - llamado al comienzo de toda la prueba
  • beforeEach - llamado antes de cada transacción HTTP
  • before - llamado antes de alguna transacción HTTP específica
  • beforeEachValidation - llamado antes de que se valide cada transacción HTTP
  • etcétera…

O, si quieres conectarte después transacciones, cambie la palabra 'después' por 'antes' en las funciones anteriores. El uso de ganchos lo ayudará a evitar errores que resulten de problemas de seguridad, ayudar a limpiar después de los pasos de prueba, depurar y cambiar / establecer expectativas.

La mala noticia es que crear todos los ganchos que necesita no es una experiencia especialmente divertida, especialmente si necesita crearlos para muchas transacciones diferentes en una prueba. “Es como escribir pruebas de integración ... pero incluso menos divertido. Pero, lamentablemente, no reemplaza las pruebas de integración ”, dice Weßling. Aún así, es uno que es necesario para obtener todos los beneficios.

Rouven comenta que "si solo prueba su GET solicitudes, está haciendo más de lo que la mayoría de la gente hace" pero, si alguna vez se ha enfurecido con documentación inexacta, seguramente verá el valor de hacer un esfuerzo adicional para probar el el resto de las llamadas a la API también. Y, con la ayuda de algunas de las herramientas disponibles, todo este proceso no tiene por qué tomar tanto tiempo como podría pensar.

Lea también: 9 errores comunes cometidos durante las pruebas de API

¿Con qué frecuencia debería realizar la prueba?

En opinión de Weßling, esto no es algo que deba hacer cada pocas semanas, sino cada vez que realiza un ajuste en su API o en la documentación asociada a ella. Probablemente suene como mucho para asumir, especialmente si está integrando continuamente código nuevo o si es parte de un equipo que ya se está expandiendo demasiado, por lo que es una gran idea automatizar este proceso.

Hay una variedad de herramientas disponibles para ayudar a los desarrolladores de API que buscan probar su documentación, como Swagger Test Templates o Hippie Swagger. Debido a que Weßling usa y recomienda Dredd , nos quedaremos con eso aquí.

Dredd toma una especificación API Blueprint o Swagger y valida si las funciones de la API de producción son como se describen en su documentación. Es independiente del lenguaje, compatible con PHP, Go, Python, Ruby y otros lenguajes. Si lo usa con Travis CI, CircleCI, Jenkins u otro CI basado en * nix, puede usarlo en conjunto con la integración continua .

El uso de algo como Travis CI para las pruebas es útil porque le notificará los errores en tiempo real en lugar de si los agrupa con sus pruebas de integración nocturnas. Y emparejarlo con Apiary es aún mejor, porque le permite revisar los resultados de las pruebas en un formato más fácil de usar en lugar de tener que buscar en los registros de CI. Una vez que haya configurado con éxito este proceso, realmente puede configurar y olvidar la documentación de la API porque cualquier cambio que realice se probará automáticamente.

¿Intenta automatizar las pruebas de API? Leer: 10 herramientas de integración continua para impulsar el desarrollo de API

Problemas comunes de prueba de documentación de API

Desafortunadamente, debido a que no hay mucha estandarización en lo que respecta a las pruebas de documentación de API, todavía no existe un proceso sencillo paso a paso para pasar de las pruebas manuales a la automatización de la experiencia. Al menos, no sin algunos contratiempos en el camino.

Algunos de los problemas que encontró Weßling, que también pueden aplicarse a su API, son los siguientes:

  1. Las pruebas de API se encontrarán con problemas de limitación de velocidad , por lo que debe establecer un tiempo de espera.
  2. Es posible que deba usar enlaces para cambiar los datos de la solicitud antes de que se envíe una solicitud si, por ejemplo, un ejemplo particular en su documentación requiere una clave de autorización.
  3. Las claves de API no públicas pueden provocar problemas de seguridad . En este caso, deberá anular cosas como los encabezados de autorización, nuevamente usando ganchos, antes de que se envíe al registro. De lo contrario, como bromea Weßling, "lo vas a pasar mal".
  4. Mutar o eliminar datos innecesarios creados al probar las operaciones CRUD (Crear, Leer, Actualizar, Eliminar) durante el proceso de prueba de API.

Configurar la automatización de las pruebas de documentación de API es algo que requiere una importante inversión de tiempo inicial  porque, seamos sinceros, no todo saldrá necesariamente bien la primera vez. Pero, por supuesto, vale la pena por el tiempo que ahorrará a largo plazo.

Las pruebas de documentación de API eventualmente serán una práctica estándar

Es posible que se busca en este post y se pregunta si o no usted tiene que añadir las pruebas de documentación de la API automática a la creciente montón de prácticas de diseño y herramientas API suplementario. En este momento, quizás no sea tan crítico. Pero creemos que Weßling está en algo cuando coloca una diapositiva que muestra que el "error de documentación" de búsqueda tiene más de 225 millones de resultados en Google.

Las empresas centradas en el cliente ya están probando su documentación por miles, y la documentación de API estable y predecible seguirá siendo un sello distintivo de la experiencia de calidad del desarrollador . Especialmente a medida que las API se vuelven más dominantes , la documentación completa y actualizada con sandboxes interactivos se volverá aún más importante de lo que ya son.

Los desarrolladores de API que descuidan su documentación / especificación pueden salirse con la suya sin implementar la validación automática de actualizaciones por un tiempo más, pero corren el riesgo de quedarse atrás en los próximos años.

Publicar un comentario

0 Comentarios