Header Ads Widget

Ticker

6/recent/ticker-posts

OEA vs. RAML: ¿Cuál es la diferencia?

 

OAS y RAML son dos formatos de descripción de API populares . Aunque fueron diseñados para propósitos ligeramente diferentes, muchos propietarios de API solo usan uno u otro, lo que plantea la pregunta: ¿cuál de los dos debería elegir?

En este artículo, ofrecemos una comparación concisa de OpenAPI Specification (OAS) y RESTful API Modeling Language (RAML). Discutimos para qué fueron construidos y qué tan bien se han mantenido. Terminamos explicando por qué OAS es el estándar de la industria y el formato de especificación lógica para la mayoría de los proveedores de API RESTful, y por qué está configurado para permanecer así.

 


¿Qué es la OEA?

Lo más probable es que ya esté familiarizado con la especificación de OpenAPI (OAS). Este popular lenguaje de especificación se posiciona como una herramienta para describir API, estableciendo una especie de contrato entre el proveedor de API y el consumidor, pero también ofrece varios beneficios de automatización en documentación y pruebas .

Vale la pena saber que la especificación OpenAPI (entonces conocida como Swagger ) perteneció una vez al software SmartBear. Aunque la organización todavía tiene vínculos estrechos con la especificación, ahora se rige por la Iniciativa OpenAPI , una comunidad de código abierto respaldada por la Fundación Linux.

Puede ver un ejemplo de cómo se ve un documento OAS 2.0 cargando el Swagger Editor . La especificación captura mucha información sobre la API en cuestión, que cubre metadatos básicos, así como métodos de recursos, parámetros, respuestas y más:

 paths: /pet: post: tags: - "pet" summary: "Add a new pet to the store" description: "" operationId: "addPet" consumes: - "application/json" - "application/xml" produces: - "application/xml" - "application/json" parameters: - in: "body" name: "body" description: "Pet object that needs to be added to the store" required: true schema: $ref: "#/definitions/Pet" responses: "405": description: "Invalid input" security: - petstore_auth: - "write:pets" - "read:pets"

¿Qué es RAML?


RAML, o RESTful API Modeling Language, es un formato de descripción de API basado en YAML lanzado por Mulesoft a finales de 2013. Como lenguaje de modelado, el objetivo principal de RAML es ayudarlo a diseñar nuevas API, y no solo describir las API existentes.

Si bien RAML se creó teniendo en cuenta las API REST, es lo suficientemente flexible como para que se pueda usar para modelar otros estilos arquitectónicos, incluidos RPC e incluso GraphQL .

"Dado que RAML admite cualquier lenguaje de esquema, puede admitir virtualmente cualquier tipo de API siempre que estén basados ​​en HTTP". - Jonathan Stoikovitch, líder de estándares abiertos en MuleSoft

Ahora, pasemos a algunas especificaciones de muestra. Al igual que otros estándares de descripción, un documento RAML comienza con algunos metadatos API esenciales:

 

title: e-BookMobile API
baseUri: http://api.e-bookmobile.com/{version}
version: v1

Posteriormente, puede comenzar a describir los diversos recursos y subrecursos de su API, como los métodos HTTP que toman y los parámetros de consulta que puede pasar:

/books:
  /{bookTitle}
    get:
      queryParameters:
        author:
        publicationYear:
        rating:
        isbn:
    put:
      queryParameters:
        access_token:

Y de manera similar, para cada recurso o subrecurso, puede describir las respuestas que su API devolverá para varias llamadas, proporcionando cargas útiles de muestra:

/books:
  /{bookTitle}:
    get:
      description: Retrieve a specific book title
      responses:
        200:
          body:
            application/json:
              example: |
                {
                  "data": {
                    "id": "SbBGk",
                    "title": "Stiff: The Curious Lives of Human Cadavers",
                    "description": null,
                    "datetime": 1341533193,
                    "genre": "science",
                    "author": "Mary Roach",
                    "link": "http://e-bookmobile.com/books/Stiff"
                  },
                  "success": true,
                  "status": 200
                }

Elegir entre RAML y OAS

Aunque RAML se enfoca en modelar API y OAS en describirlas, la verdad es que cualquiera de los formatos se puede usar para cualquier propósito: puede describir una API existente con RAML o modelar una nueva con OAS. Entonces, ¿qué formato deberías elegir?

Caracteristicas

En su mayor parte, RAML y OAS 2.0 comparten muchas de las mismas características. Puede describir (o modelar) recursos, métodos y parámetros de consulta, compartir respuestas de ejemplo y definir esquemas de seguridad en ambos formatos, solo que con estructuras ligeramente diferentes.

Es la versión más nueva de OAS, 3.0 , que ofrece muchas más funciones, como definiciones de seguridad adicionales, soporte para devoluciones de llamada y referencias hipermedia , así como una estructura de archivos optimizada. Sin mencionar que la versión 3.1 trae aún más desarrollos:

“Estoy muy contento de que en 3.1 las definiciones de esquema se basen en un esquema JSON" verdadero "sin elementos específicos de OpenAPI. Y estoy aún más feliz (si no totalmente loco) porque por fin podremos anular alguna información, como la descripción, proveniente de un esquema al que se hace referencia $ref”. - Arnaud Lauret alias The API Handyman

Dicho esto, una característica por la que RAML todavía es alabada hoy es la reutilización:

“Si tuviera que elegir un aspecto en el que RAML sobresale, diría que es el aspecto de la“ reutilización ”. RAML se envía con su propio sistema de tipos que ayuda a modelar estructuras de datos utilizando características como herencia e incluso herencia múltiple, lo que ayuda a que las definiciones de esquema y API sean muy secas, haciéndolas mucho más fáciles de leer (y comprender); RAML también tiene los conceptos de "esquemas de seguridad", "tipos de recursos" y "rasgos" que permiten modelar, solo una vez, las características más comunes de los recursos y métodos HTTP ". - Jonathan Stoikovitch

Actividad

Cuando se trata de comunidad, la Especificación OpenAPI está más establecida de los dos formatos de descripción: el repositorio de OAS tiene más de 18,000 estrellas en GitHub, frente a las 3,700 de RAML más o menos. Una mayor participación comunitaria facilita el intercambio entre socios y aumenta la cantidad de herramientas disponibles.

Por supuesto, con la comunidad viene la actividad. Desafortunadamente, esto significa que RAML no ha progresado como lo ha hecho la OEA en los últimos años. RAML todavía está en la versión 1.0 (con el último parche importante en julio de 2016 ), donde OAS está ahora en la versión 3.0 con nuevas versiones en proceso.

Curiosamente, los desarrollos más recientes relacionados con RAML en realidad buscan permitir la conversión entre los dos formatos:

“Recientemente, desaprobamos nuestros analizadores de Java y JavaScript oficiales y lanzamos un nuevo analizador llamado webapi-parser que es compatible con RAML y OpenAPI / OAS. Esto es excelente para la comunidad porque significa que cualquier herramienta que sea compatible con OpenAPI ahora se puede aprovechar con RAML y viceversa ". -Jonathan Stoikovitch

Parecería que RAML no se está utilizando en la naturaleza tanto como esas 3.700 estrellas de GitHub te harían creer. La mayoría de los subprocesos de StackOverflow con la etiqueta RAML en realidad provienen de usuarios de los productos de creación e integración de API de MuleSoft, como Mule y Anypoint Studio, donde RAML es el formato de descripción de API nativo.

¿La comida para llevar? RAML siempre ha sido parte del ecosistema MuleSoft, lo que puede explicar su uso continuo a pesar de la falta de nuevos desarrollos. Sin embargo, con MuleSoft que ahora se está entusiasmando con el uso de OAS 3.0 en sus productos , es difícil imaginar que la actividad RAML aumente mucho más allá de ese ecosistema de aquí en adelante.

Veredicto final

Dentro de una industria de muchos estándares , RAML y OAS se destacan como formatos poderosos para modelar y / o describir API. Aunque su estructura y sintaxis son similares, existen diferencias notables en los conjuntos de características y la actividad de sus comunidades. Si bien RAML puede ser la especificación lógica para usar para algunos desarrolladores de MuleSoft o en circunstancias particulares, la Especificación OpenAPI parece ser un estándar de la industria, reflejado por su continuo desarrollo y soporte en la comunidad de API .


Publicar un comentario

0 Comentarios