Header Ads Widget

Ticker

6/recent/ticker-posts

¿Hasta dónde deben llegar los lenguajes de definición de API?

 

¿Hasta dónde deberían llegar los lenguajes de definición de api?

Los lenguajes de definición de API más comunes que detectamos en la naturaleza son Swagger / OpenAPI Spec , RAML y API Blueprint . Los tres le permiten definir sus puntos finales, sus recursos, sus parámetros de consulta o ruta, sus encabezados, códigos de estado, esquemas de seguridad y más.

En pocas palabras, estos lenguajes de definición definen la estructura de su API y le permiten describir muchos elementos . Sin embargo, a medida que los estándares en la industria de las API evolucionan, su propósito y diseño están bajo un escrutinio continuo. Específicamente, la extensibilidad de las especificaciones de API con elementos y conjuntos de características adicionales se pone en duda.

Recientemente, se desató una discusión sobre el rastreador de problemas de especificación de API abierta sobre los principios de mundo abierto frente a mundo cerrado . En pocas palabras, la pregunta es si se supone que una definición de API describe una API completamente (incluidas, por ejemplo, las rutas a las que no tiene permitido acceder, todos los códigos de estado posibles, etc.) o si es solo una el mejor esfuerzo para describir lo que la mayoría de los consumidores de API pueden usar y necesitan, no necesariamente cubriendo todo el alcance de la API.

Toda la conversación reciente nos ha hecho pensar: ¿qué tan detalladas deben ser las definiciones de API? Se pueden imaginar muchos otros usos para un lenguaje de definición de API:

  • Las definiciones de API podrían aportar información o documentación adicional, con una narrativa y más metadatos que describan el flujo de llamadas a la API, cómo las personas que llaman podrán interactuar con la API.
  • Los proveedores de API pueden traer tales metadatos adicionales con el propósito de descubrir API, para otorgar créditos (sobre información de propiedad intelectual o derechos de autor), quizás residiendo en descriptores externos como APIs.json (un formato para ayudar a descubrir metadatos sobre una API).
  • Las cargas útiles JSON cumplen con los esquemas JSON, pero los modelos de datos podrían definirse independientemente de los tipos de medios que elija el consumidor, de modo que el consumidor pueda solicitar cualquier formato de salida, pero aún así comprender la naturaleza intrínseca de los recursos que se tratan.
  • A menudo, hay rasgos comunes que se extienden a través de una API, por ejemplo, cómo hacer la paginación, y algunas definiciones de API pueden factorizar este aspecto común de una manera reutilizable y referenciable.
  • Las API de hipermedia no están necesariamente bien cubiertas en términos de modelado en las especificaciones de API más comunes, ciertamente hay algo que mejorar aquí.
  • Otro tema interesante también es cómo asegurarse de que una implementación de API se ajuste a su definición de API, o siga algunas buenas convenciones o pautas de la empresa. Se podrían proporcionar herramientas para ayudar con esta tarea.

RAML se acerca a 1.0 , se está trabajando en OpenAPI Spec con una lista de problemas que detallan qué esperar y API Blueprint publicó su hoja de ruta . Como nuestras especificaciones favoritas pronto verán evoluciones interesantes, es un buen momento para revisar la dialéctica del diseño del lenguaje de definición de API.

Veamos un poco más de cerca algunas de las proposiciones anteriores para ver si las definiciones de API brindan soluciones y analicemos si es incluso el propósito de un lenguaje de definición de API hacer este tipo de cosas. ¿Qué podríamos incorporar a la próxima generación de especificaciones de API para que sean realmente notables?

Relacionado:  ¿OpenAPI significa contrato de mundo abierto?

Narración de historias de API: modelado de transacciones de varios pasos dentro de la documentación

Los proveedores de API deben ser narradores de historias. Cuando diseña una API para una base de usuarios, desea contarles una historia: cómo acceden a la API con una clave de API, cómo interactúan con la API y cuáles son las características comunes de varios recursos (paginación).

A menudo, para llevar a cabo un determinado caso de uso comercial, debe realizar varias llamadas seguidas: primero obtiene los detalles de un pedido, luego solicita los detalles del cliente y, por último, tal vez su dirección de entrega. Entonces, encadena las llamadas , utilizando elementos de la respuesta de la llamada anterior para elaborar la solicitud posterior. A veces, tiene diferentes cargas útiles, con o sin entidades integradas; una llamada de pedido puede contener todos los detalles del cliente y su dirección, o puede que no.

¿Cómo puede un proveedor explicar el escenario lógico de las llamadas? Una página publicada dentro de la documentación de la API debe describir tales escenarios y reagrupar series lógicas de llamadas en una historia coherente: los casos de uso de la API. Aunque puede proporcionar descripciones de los parámetros de la API utilizando los lenguajes de definición actuales, no hay forma de unir elementos en un flujo de trabajo coherente Una definición de API con el poder de contar historias de API que describan instancias comunes de transacciones de varios pasos podría ser muy poderosa.

Escenarios de prueba

En relación con estos casos de uso, sería útil tener pruebas correspondientes a esos escenarios. Por ejemplo, DHC by Restlet tiene su propio formato de definición de escenario de prueba que puede usar para ejecutar pruebas desde un complemento de Maven o dentro de su canal de integración continua con el servidor Jenkins. ¿Podrían estas pruebas de escenario derivarse de la definición de API o integrarse dentro de la propia definición de API? Curiosamente, la hoja de ruta de API Blueprint enumera escenarios y pruebas , por lo que esto podría llegar más temprano que tarde.

Documentación vs especificación

Es fácil mezclar la diferencia entre el formato de definición de API con la documentación de API publicada Aunque son entidades diferentes, puede generar la documentación a partir de la definición; no se puede negar que las dos están íntimamente vinculadas. Si estuvieran completamente separados, los formatos de definición de API ni siquiera tendrían etiquetas de descripción, ya que el formato probablemente solo se usaría para el consumo de máquinas y no para el consumo humano .

Con las definiciones de API, puede derivar la implementación de esqueletos para su API o SDK de cliente . Pero también puede generar documentación hermosa y completa: tal vez solo documentación HTML estática, o aderezada con una pizca de JavaScript para proporcionar un área de juegos interactiva para probar la API directamente, o ir a todo vapor con el alojamiento de esa definición en un desarrollador de API completo portal donde puede agregar capacidades de colaboración, información de versiones y más. Como la documentación del usuario final, así como los SDK y las bibliotecas pueden derivarse de la definición de API principal, los dos están intrínsecamente vinculados.

Guía de estilo, conformidad y herramientas

guía-de-estilo-nordic-apis-definición-lenguajes-api

Al diseñar una API, es probable que su empresa ya haya creado un conjunto de pautas o mejores prácticas a seguir. Por ejemplo, consulte la guía de estilo API de Paypal . El documento describe las estructuras generales de los URI, un elemento de espacio de nombres obligatorio, un método de paginación que debe permanecer consistente y más. Sus propias pautas pueden especificar convenciones de nomenclatura, como el uso de camel-case.

Sería útil evaluar automáticamente si la API realmente cumple con esas pautas . Mantener este tipo de conformidad podría ser parte de la definición de API en sí o existir como un documento externo al que se hace referencia desde la definición de API. Esto podría requerir un nuevo formato que describa estas reglas de convenciones, lo que lleva a uno a considerar si tales pautas deben definirse declarativamente o si se podría usar un lenguaje de scripting para necesidades de validación más avanzadas.

Además de tener un archivo de descripción de pautas especial, se necesitarían herramientas para verificar que la implementación de la API realmente se ajuste a esas pautas. Es probable que estas herramientas no formen parte de un formato de definición de API, pero podrían acompañarlo y ofrecerse en varios idiomas y conjuntos de tecnología con los que cualquiera puede sentirse como en casa.

Hipermedia

Uno de los principios clave del estilo arquitectónico REST acuñado por Roy Fielding es el hipermedia, con hipermedia como motor del estado de la aplicación (HATEOAS). Más API se ajustan a esta restricción, y existen varios enfoques para definir esos enlaces hipermedia: hemos definido los tipos de hipermedia HAL, JSON-LD y Siren en una publicación de blog anterior .

Aunque el concepto es popular, los lenguajes de API a menudo no le permiten describir fácilmente estas API impulsadas por hipermedia. ¿No deberían ayudar a los usuarios a describir tales metadatos e hipervínculos? Zdenek Nemec de Apiary dio un ejemplo de implementación de HAL para una API , utilizando las nuevas capacidades de modelado MSON de API Blueprint. Quizás en un futuro cercano, los lenguajes de API admitirán una marca en particular para indicar qué enfoque hipermedia está utilizando la API.

Aprenda a mejorar la experiencia de la API con Hypermedia

Modelado de datos y carga útil

Hablando de MSON (Markdown Syntax for Object Notation), también es una forma interesante de modelar las cargas útiles de su API. Con un formato conveniente y legible, que no es ni un esquema JSON ni un esquema XML, puede describir cómo se verán sus datos, independientemente del tipo de medio subyacente que se utilice.

Esto plantea la pregunta de si se puede admitir alguna carga útil posible de esa manera. Después de todo, las API esotéricas probablemente no se ajustarán al esquema JSON, al esquema XML o al MSON. Es probable que haya diferencias de expresividad entre todos ellos. ¿Deberían los lenguajes de definición de API ser prescriptivos y limitarse a los casos de uso cuerdos 80/20 de modelado de datos?

Otro ejemplo es la reciente especificación Rapier API de Apigee , cuyo objetivo es describir las API orientadas a datos con entidades y sus relaciones. Es posible que Rapier se contribuya a la especificación OpenAPI en algún momento, pero existen límites claros en términos de expresividad.

Extensiones de definición de API

Aunque los lenguajes de definición de API no proporcionan necesariamente todas esas comodidades, un aspecto importante es la extensión . Por ejemplo, Swagger / OpenAPI Spec proporciona la noción de extensiones . Los diseñadores de API tienen la capacidad de definir campos personalizados (siguiendo una convención) dentro de los cuales pueden incluir los datos o metadatos que deseen. Entonces, si desea agregar punteros de documentación de pautas o pruebas asociadas, puede agregarlos como extensiones personalizadas. Luego, tus propias herramientas pueden asimilar esas extensiones específicas y manejarlas como quieras.

Por ejemplo, las herramientas que traducen de un lenguaje de API a otro pueden almacenar extensiones personalizadas que describen cómo hacer mejor la traducción, en particular en el caso de que una especificación no admita ciertos metadatos que admite la otra. Sin embargo, tengamos en cuenta una desventaja de las extensiones personalizadas: no todas las herramientas y proveedores las entienden, y son algo propietarias y no portátiles. ¡Úselo bajo su propio riesgo!

Para obtener más información sobre el diseño de API, visite nuestro Centro de conocimientos

Pensamientos finales

Bien, entonces, ¿deberían los lenguajes de definición de API proporcionar todo y el fregadero de la cocina? Si es así, ¿cuál es el umbral? ¿Dónde ponemos el cursor? O, ¿una definición de API debería limitarse a describir los diversos elementos de la API y luego aprovechar un formato complementario como APIs.json para agregar y vincular a recursos adicionales?

Es evidente que hay ventajas en impulsar un poco más los lenguajes de definición de API y proporcionar más información que ellos. Las extensiones son el camino a seguir, siempre que definamos, publiquemos y compartamos dichas extensiones de una manera un tanto estandarizada. Pero algunos definitivamente sienten la necesidad de ir más allá de lo que se ofrece hoy. ¿Cuál es tu opinión sobre eso? ¿Dónde pondrías el cursor?

¡No dude en comentar a continuación y asegúrese de registrarse en nuestro boletín de noticias para futuras ideas sobre el diseño de API!

Publicar un comentario

0 Comentarios