Header Ads Widget

Ticker

6/recent/ticker-posts

Revisión de óptica

Revisamos Optic, una herramienta para documentar automáticamente y probar API

Hay pocas cosas tan importantes para la experiencia del desarrollador de API como las especificaciones de API y la documentación de API . Ambos proporcionan un conducto vital entre el proveedor de API y el usuario desarrollador, expresando información crítica sobre aspectos funcionales de la API.

Dado que estos recursos para desarrolladores son tan importantes, significa que esta fuente de verdad debe ser infalible . Desafortunadamente, muchas API funcionan de manera diferente en la práctica con respecto a lo que afirman en la documentación. Este es un problema central al que muchos desarrolladores tienen que encontrar una solución en algún momento de su proceso de desarrollo.

Hoy, vamos a echar un vistazo a Optic , una solución que pretende ayudar a establecer una fuente confiable de verdad, sincronizando el comportamiento funcional y real de la propia API. ¿Lo hace bien? Más importante aún, ¿lo hace de forma limpia o solo sirve para aumentar la carga de trabajo del desarrollador promedio? Vamos a averiguar…

Caso de uso indicado de óptica

La cuestión central planteada por Optic para justificar su enfoque es la idea de que las herramientas actuales simplemente no son tan fáciles de desarrollar. Si bien hay otras herramientas que posiblemente mejoran la experiencia del desarrollador cuando se trata de diseño e implementación, su principal problema declarado de dificultad para sincronizar la especificación, la documentación y la funcionalidad práctica es ciertamente válido. Sí, es posible utilizar herramientas modernas para escribir archivos OpenAPI, generar código, crear pruebas de contrato, etc., pero según Optic, el proceso de hacer todo eso, incluso en aplicaciones que pretenden ser "amigables para el desarrollador". es a menudo muy desordenado y deficiente.

La solución de Optic a esto es cambiar la relación entre el código base en sí y la función real de dicha base. Por lo general, estos dos elementos están desacoplados: se repite el código base y, una vez hecho, se sincroniza con la especificación y la documentación. A veces, la sincronización y la documentación se pueden cambiar, reflejando este cambio en la base de código. Si bien este enfoque suele ser bastante efectivo para garantizar que los cambios estén documentados, sigue siendo un proceso manual que requiere que un desarrollador inicie el sistema subyacente.

La solución óptica es hacer que su oferta vigile el tráfico e inicie cambios en la documentación y las especificaciones a medida que se produzcan los cambios reales. Al hacer que el sistema detecte un cambio probando la función contra el valor establecido, se crea una especie de "sistema de desconfianza". Este sistema de desconfianza puede probar constantemente la documentación y garantizar que a través de esta prueba, esté actualizada y sea precisa en términos de los resultados funcionales relacionados con la base de código que la generó.

Optic menciona algunos casos de uso específicos para el producto, pero estos se pueden resumir generalmente por lo que resulta. Optic tiene la intención de crear una manera fácil de escribir especificaciones de OpenAPI en minutos, garantizar que sean precisas en todo momento y detectar automáticamente cuando la actividad real del mundo real no coincide, más concretamente, la solución indicada también proporciona un método limpio, fácil y en su mayoría automatizado para actualizar esto internamente en un esfuerzo por mejorar la experiencia general del desarrollador. Optic también ofrece una herramienta de análisis de API relativamente robusta para rastrear el uso real en el mundo real para ayudar en el desarrollo; esto, combinado con código, SDK y colecciones de cartero generación, tiene como objetivo proporcionar una propuesta de valor sólida tanto para el desarrollador como para el usuario. Hacer cumplir los cambios en las reglas para evitar cambios importantes y proporcionar herramientas para admitir las guías de estilo de la API podría elevar la oferta de un desarrollador en su conjunto.

Lea también: Generación automática de una CLI a partir de una especificación de OpenAPI

Escenario de ejemplo

Como parte de su documentación, Optic proporciona un flujo de escenario de muestra para demostrar cómo funciona el sistema.

En nuestro ejemplo, Optic ha notado que una nueva solicitud POST en la ruta / todos. Cuando se detecta tráfico en esta ruta, Optic lo marca automáticamente para su revisión y lo envía a través de su interfaz de usuario. Aquí, podemos ver a Optic mostrándonos estos primeros pasos:

Ahora que estamos en el sistema óptico, podemos empezar a hacer algunas cosas interesantes con la ruta recién marcada. Una cosa que podemos hacer es proporcionar un Path Matcher, que permitirá a Optic agrupar rutas similares para la misma operación. Esta es una excelente manera de controlar la expansión de los terminales a través de funciones repetidas y rutas replicadas, y más concretamente, es una excelente manera de enseñarle a Optic lo que debe esperar cuando se trata de nuevas solicitudes bajo la misma estructura de ruta.

Ahora que hemos definido la ruta, debemos documentar lo que hace la solicitud. En nuestro caso, nuestra ruta le permite a un usuario agregar una nueva entidad al área "Tareas" de la aplicación; como tal, la ruta permite literalmente "Agregar una nueva tarea", que hemos agregado aquí. como la función de solicitud indicada. Ahora que se adjunta, se agregará a la documentación.

Una de las mejores cosas que hace Optic es operar un motor diferencial para detectar cambios cuando ocurren y mostrar qué diferencias funcionales en la actividad están representadas. En nuestro caso, no solo se detectó la nueva función y ruta, sino que también se detectó una nueva forma de cuerpo de solicitud. "IsDone" y "task" se proporcionaron en la solicitud y, como tal, Optic solicita la capacidad de agregar esta forma a la especificación. En el futuro, esta forma se puede utilizar para todas las solicitudes de esta forma y tipo, de conformidad con la actividad real con el diseño de especificación establecido.

Con todo esto hecho, podemos ver el resumen de los cambios pendientes. Tenemos un nuevo flujo de función de punto final, una forma de solicitud establecida y cuál es el formato y el significado de la respuesta. Desde aquí, si decidimos aplicar estos cambios, podemos hacer que la especificación tome esta nueva información y se actualice para uso futuro.

Este caso de uso de varios pasos es excelente y realmente expone lo simple y limpia que es la interfaz. Optic también adopta una metodología de estética limpia y fácilmente comprensible en esta herramienta.

Lea también: 5 formas en que OpenAPI estimula la agilidad de la API

Pros

La mejor ventaja que tiene Optic es el hecho de que la experiencia es extremadamente ágil. El problema en cuestión es funcionalmente de enfoque y diseño, y Optic ciertamente ha prestado atención a la calidad del diseño. La interfaz de usuario es intuitiva, limpia y eficiente, y la metodología guiada que utiliza para ayudar en la documentación de funciones y rutas es absolutamente fantástica.

El sistema diferencial utilizado aquí también es muy bueno y bastante eficaz por varias razones. En primer lugar, el valor obvio viene con el hecho de que el desarrollador descubre diferencias que de otro modo quedarían ocultas. Parece una cosa pequeña (y más concretamente, parece algo obvio de implementar), pero la realidad del desarrollo moderno es que nuestras bases de código son a menudo grandes, tienden a "enterrar" información debajo de una salida demasiado detallada y extremadamente compleja. contexto. Sacar a la luz esta información es vital para un buen desarrollo.

En segundo lugar, este enfoque de pantalla de comparación de "diferencias" es una manera asombrosa de, de un vistazo, aislar problemas potenciales. Solo ver la diferencia está bien, pero poder ver la diferencia en comparación con el resultado esperado permite una comparación uno a uno, lado a lado, que permite una mayor precisión y comprensión. Nuevamente, esto puede parecer un aspecto increíblemente simple de incluir aquí, pero este tipo de mejoras de "calidad de vida" para los desarrolladores toma una herramienta "buena" y la eleva a verdaderamente excelente.

Contras

Una desventaja clara que viene con el uso de algo como Optic es que aleja la responsabilidad del desarrollo sensato del desarrollador. Puede parecer contradictorio que una herramienta destinada a facilitar la vida del desarrollador pueda producir peores resultados, pero hay algo que decir a favor del argumento de que puede permitir malas decisiones. Cuando se desarrolla una API, la documentación con la que está vinculada debe mantenerse actualizada por la función misma de planificar la API desde cero. Si bien las iteraciones y los cambios secundarios ocurren, los cambios no deben ser tan fortuitos y tan extremos como para documentarlos primero a través de Optic.

Eso no quiere decir que una planificación adecuada solucione todas las situaciones en las que Optic puede brillar. Como se mencionó, estos cambios laterales ocurrirán, y Optic es ideal para ese caso de uso. Quizás la mejor sugerencia, entonces, es ver Optic no como una solución en sí misma a un problema central, sino como una herramienta que ayuda a resolver ese problema. En otras palabras, Optic debe usarse como la “pantalla” que detecta las rutas y funciones no documentadas en lugar del método principal utilizado para documentarlas.

Por supuesto, este es un punto en gran parte subjetivo: si un desarrollador está documentando todas las rutas y funciones usando Optic, entonces se podría argumentar que la experiencia del usuario no es diferente de una API que está bien planificada con anticipación. Su kilometraje puede variar y, al igual que con cualquier herramienta API que analicemos, debe evaluar su situación y averiguar si esta es una parte valiosa de su flujo de trabajo.

Conclusión

Optic es una gran herramienta en el sentido de que sirve para unir limpiamente la lógica de la API con su implementación práctica. Si bien se podría argumentar que Optic es una solución a un problema que los desarrolladores deberían resolver mediante la planificación y el desarrollo concienzudo, la realidad es que el problema existe; por lo tanto, Optic como solución debe considerarse como lo que es en el contexto de Que hace. Bajo esa consideración, Optic es una solución maravillosamente poderosa e intuitiva que permite un desarrollo eficiente y limpio.

Ya sea que su caso de uso esté unificando la documentación con las API directamente o simplemente capturando todo el desarrollo periférico, Optic es una excelente opción. ¿Qué opinas de Optic? ¿Hay otras herramientas que cree que hacen mejor el mismo trabajo? ¡Háganos saber en los comentarios a continuación!

Publicar un comentario

0 Comentarios