Header Ads Widget

Ticker

6/recent/ticker-posts

Tutorial de APIcurio

 Realizamos un recorrido utilizando APIcurio, un editor de diseño de API compatible con OpenAPI Spec.

Tener una API completamente documentada y legible por máquina se considera un desarrollo de primera línea. Sin embargo, crear un formato coherente para la API y la documentación es un desafío sin una guía o estructura externa. En un esfuerzo por proporcionar esta estructura a los creadores de API, se introdujo la Especificación OpenAPI . Si bien la especificación es indudablemente efectiva, es bastante detallada y, por lo tanto, difícil de dominar.

Apicurio Studio , mantenido por el Programa de desarrolladores de Red Hat, es una herramienta para diseñar API que sigue la especificación sin requerir que los desarrolladores estén íntimamente familiarizados con ella. Proporciona una GUI para definir todos los aspectos de la API. En última instancia, Apicurio genera documentación legible tanto por humanos como por máquinas que cumple con la última versión de la especificación OpenAPI. Este tutorial cubre el proceso de diseño de una API con Apicurio de principio a fin y evalúa la posibilidad de utilizar Apicurio en producción.

Configuración y alojamiento

Para comenzar a usar Apicurio, primero decida si se auto-hospeda o usa su aplicación web. Para una solución a largo plazo, el autohospedaje ofrece el mayor control. Apicurio Studio es completamente de código abierto y siempre está disponible en Github . Su documentación cubre los requisitos de alojamiento y el proceso de instalación, que es bastante sencillo gracias al paquete de inicio rápido.

Por el bien de este tutorial, la aplicación web es perfecta. Simplemente registre una cuenta e inicie sesión en el sitio de Apicurio. No se requiere instalación y todas las funciones están disponibles.

Creando una API en Apicurio

Este tutorial cubre el proceso de creación de una API para una aplicación de seguimiento de la nutrición. La API debe permitir la creación de entradas en la aplicación, que se pueden editar, eliminar y consultar. También necesita una base de datos que contenga información nutricional sobre los ingredientes, que también será accesible a través de API.

Para comenzar a diseñar esta API, primero cree una nueva API desde el panel de Apicurio. En la pantalla de creación de API, puede seleccionar el tipo (también conocido como el número de versión de OpenAPI) y proporcionar un nombre y una descripción.

Una vez creada la API, haga clic en el botón editar API. La primera sección del editor contiene información general de la API. Gran parte de esta información son metadatos bastante básicos, como el número de versión y la información de contacto. En esta pantalla también se pueden especificar varias licencias de código abierto para la API.

Vale la pena señalar algunas secciones, ya que entrarán en juego más adelante cuando se defina la funcionalidad principal de la API: estas son las definiciones de servidor y seguridad. Estos datos se utilizan al crear las rutas más adelante. Las definiciones de seguridad incluyen opciones estándar como una clave API u OAuth , que se pueden implementar como requisitos.

También se pueden crear uno o más servidores, por ejemplo, un servidor de producción y uno de desarrollo. Las variables del servidor están integradas y se pueden usar para definir cosas como el número de puerto o la versión de API . Tenga cuidado de incluir valores predeterminados para todas las variables del servidor o se producirá un error.

Agregar definiciones de API

Una vez que se crea la API, el siguiente paso es agregar algunas definiciones básicas. Observe aquí que lo que la especificación OpenAPI llama objetos de tipo de medio , Apicurio llama definiciones. En este ejemplo de API de seguimiento de la nutrición, se requieren dos definiciones. Uno definirá la estructura de una entrada en el diario y otro definirá la estructura de un ingrediente que se encuentra en la base de datos.

Para agregar una definición, haga clic en el botón y especifique un nombre. A partir de ahí, simplemente agregue las propiedades requeridas a la definición. Al agregar una propiedad, primero agregue el nombre. Luego, haga clic en la propiedad para editarla y desarrollar la información. Las propiedades se pueden marcar como necesarias, y su tipo y formato se pueden especificar a partir de una lista de opciones aprobadas por OpenAPI, como cadenas, valores booleanos y matrices.

La definición de ingrediente también recibe algunas propiedades adicionales, como calorías (un número de punto flotante), tamaño de la porción (una cadena) y una imagen asociada (una cadena). La definición de Entrada se crea al igual que la definición de ingrediente, agregando propiedades como la fecha (una cadena con formato de fecha) y el nombre (una cadena) de la Entrada.

La mayoría de las propiedades son bastante simples, pero vale la pena señalar que una definición puede hacer referencia a otra definición. En el caso de una entrada, una propiedad (ingredientes) es una matriz de objetos Ingrediente que hacen referencia a la definición anterior.

Agregar rutas de API

Una vez creadas las definiciones, continúe con la creación de rutas de API. Las rutas especifican todos los diferentes puntos finales de la API y las operaciones que tienen lugar en las diferentes rutas. Si bien las definiciones son relativamente simples, las rutas contienen muchas capas de información. No solo se especifican las rutas, sino que se describen las solicitudes y las respuestas, se implementan la seguridad y los servidores, se proporcionan parámetros de consulta y mucho más.

Para agregar una ruta, simplemente haga clic en el enlace y especifique la URL de la ruta. El primero en este ejemplo de nutrición es /entries/, que de manera predeterminada devolverá los 5 artículos de entrada más recientes enviados por el usuario. En la pantalla de edición de esta ruta, primero especifique las operaciones aplicables. En este caso, es simplemente una operación GET para recuperar los elementos de entrada. Seleccione OBTENER y agregue una breve descripción que describa la operación.

La especificación de OpenAPI requiere que todas las operaciones especifiquen como mínimo el tipo de respuesta. Haga clic en el enlace OBTENER para ir a la pantalla de detalles de esta operación y luego seleccione el enlace para agregar una respuesta. Para una solicitud GET simple, el código de estado es 200. Desde allí, puede especificar la descripción, así como el tipo de medio que devuelve la solicitud. En el caso de la /entries/ruta, el contenido devuelto será JSON que contiene una matriz de elementos de entrada. Si se desea, se puede proporcionar un cuerpo de respuesta de ejemplo.

Esta ruta también admite algunos parámetros de consulta, que pueden especificarse fácilmente. Al igual que las propiedades de definición, los parámetros de consulta pueden tener descripciones, tipos y formatos asociados y ser obligatorios u opcionales.

Desde aquí, las rutas de la API se pueden versionar para satisfacer cualquier necesidad. Otros tipos de operaciones incluyen el estándar PUT, POST, DELETE y varios más. Los servidores y las medidas de seguridad definidas en la descripción general de la API también se pueden agregar a cualquier ruta.

Para algunas rutas, es posible que se requieran parámetros. En este rastreador de nutrición, por ejemplo, un usuario debería poder proporcionar una fecha específica y obtener cualquier entrada que coincida con esa fecha. Para utilizar los parámetros de ruta, simplemente cree una nueva ruta y use {} alrededor del parámetro.

Una vez que se crea la ruta, los parámetros de la ruta aparecen como una nueva sección en la pantalla de diseño de la ruta. Cualquier parámetro con nombre se coloca automáticamente en la sección de parámetros de ruta, pero debe definirse específicamente. Para hacerlo, haga clic en el botón crear y luego edite para agregar una descripción. El tipo de parámetro y el formato también se pueden seleccionar; para esta ruta, una cadena con formato de fecha es la opción adecuada.

Validación y errores de API

Debido a que Apicurio es una herramienta específicamente para crear API que cumplen con la especificación OpenAPI, la validación es una consideración importante. Apicurio hace un buen trabajo al resaltar cualquier error encontrado en toda la API, ya sea información faltante, selección de datos no válidos o uso de funciones que no están diseñadas para usarse juntas.

Los errores se resaltan inmediatamente, tanto en la barra lateral como dentro de la ruta o definición problemática. En este ejemplo, se ha creado una operación GET para la ruta de la fecha, pero no se ha especificado ninguna respuesta. Una respuesta es una parte necesaria de cualquier operación, de acuerdo con la especificación de OpenAPI, por lo que se marcan la ruta y la operación problemáticas. Al hacer clic en la información sobre herramientas, se revelan los errores en cuestión.

También está disponible un rastreador de problemas, con una lista de los problemas de validación encontrados en la API. Cada problema incluye un enlace directo al problema, lo que permite una resolución más rápida.

Colaboración y publicación

La mayoría de las veces, una API tiene todo un equipo detrás. La colaboración es un aspecto importante de cualquier herramienta de diseño de API y Apicurio Studio ofrece oportunidades para una colaboración total. Empiece por invitar a cualquier usuario, un proceso que molestamente implica generar una URL única y enviarla al usuario individual. El usuario puede entonces crear una cuenta y aceptar la invitación para colaborar.

Una vez que el usuario está dentro, la colaboración es simple y directa. Todos los usuarios tienen la capacidad de editar toda la API y todos los cambios se publican en un feed de actividades. Esto asegura que todos los cambios se puedan rastrear hasta el usuario original, en caso de preguntas o inquietudes.

Una vez completado el diseño de la API, hay algunas opciones disponibles para exportar o publicar la API. Estas opciones están escondidas en el menú de la pantalla de descripción general de la API. YAML y JSON legibles por máquina se pueden descargar directamente, o el código se puede publicar en un repositorio vinculado (por ejemplo, Github o BitBucket).

La opción más interesante (todavía en fase beta) es la posibilidad de generar un proyecto funcional . Este proyecto incluye una implementación de arranque de la API especificada, proporcionando una pequeña base que es particularmente útil para demostraciones y MVP. Actualmente, los proyectos están limitados a Thorntail Jax-RS, pero las opciones futuras incluyen Node.js y Vert.x.

El bueno y el malo

Apicurio Studio tiene muchas características que vale la pena destacar. Es una herramienta sólida para generar ideas y diseñar una API antes de que comience el desarrollo real. Apicurio ayuda al equipo a pensar realmente en toda la API y asegurarse de que se consideren todos los aspectos. Una vez que la herramienta está en funcionamiento y se ha establecido un poco de familiaridad, es bastante fácil de usar. El proceso de colaboración es simple, pero efectivo. El propietario de la API mantiene el control de todos los colaboradores aprobados, pero de lo contrario, todos pueden editar libremente. El feed de actividades proporciona solo la información suficiente, sin tener que dedicar tiempo a configurarlo.

Teniendo en cuenta lo densa que es la especificación de OpenAPI, Apicurio es una alternativa bienvenida para familiarizarse totalmente con ella. La validación de errores y el seguimiento de problemas son claros a lo largo de todo el proceso de diseño y garantizan que el cumplimiento de las especificaciones se aplique de manera adecuada. El resultado final está completamente en línea con la especificación, y la construcción de estos requisitos contribuye a la efectividad de Apicurio como una herramienta de diseño e intercambio de ideas.

Apicurio también es gratuito y de código abierto . El código siempre está disponible en Github y se mantiene con bastante regularidad. El equipo promedia una o dos actualizaciones por mes, para garantizar el cumplimiento continuo de OpenAPI y para publicar nuevas funciones.

Dicho esto, no todo es perfecto en Apicurio. Si bien es bastante rico en funciones, la interfaz de usuario podría necesitar un poco de pulido, especialmente para los nuevos usuarios. Incluir información sobre herramientas o un recorrido inicial de la interfaz ayudaría a señalar cómo se debe usar la aplicación y qué significan los diferentes términos. Vincularse con recursos externos también es una buena opción.

Otro problema recurrente fueron las características profundamente ocultas . Muchos elementos importantes se encuentran en los distintos menús y es difícil recordar qué menú en qué pantalla contiene la función deseada. Esto puede llevar a un esfuerzo innecesario, como replicar manualmente las rutas cuando realmente existe una opción de clonación.

Finalmente, el flujo de colaboración podría ser un poco más fluido. Generar un enlace que no esté asociado con una dirección de correo electrónico específica es confuso. Crear y enviar manualmente el correo electrónico de invitación también es una experiencia insatisfactoria. Si bien es comprensible que una herramienta gratuita y de código abierto no quiera pagar por los recursos del servidor para enviar los correos electrónicos, abrir un mensaje de correo electrónico precargado en la máquina del usuario y asociar las invitaciones con correos electrónicos particulares ayudaría.

Análisis final

Apicurio tiene mucho que ofrecer y es un fuerte competidor en el dominio de las herramientas de diseño de API. Si bien, sin duda, podría usar un poco de pulido de la interfaz de usuario (y quizás un día de pruebas de usabilidad), la estructura y la validación ayudan a guiar el proceso de diseño. Apicurio obliga a los colaboradores a considerar todos los aspectos de cada camino y definición. Por lo tanto, el resultado final está mucho más pensado que simplemente desarrollar la API en vivo y luego documentarla retroactivamente.

¿Ha utilizado Apicurio para un proyecto de API? Comparta sus pensamientos (buenos y malos) a continuación.

Esta publicación es parte de nuestro esfuerzo por revisar la tecnología emergente relacionada con las API y no fue patrocinada en absoluto. Si desea compartir su proyecto con nosotros, no dude en contactarnos aquí .

Publicar un comentario

0 Comentarios