Header Ads Widget

Ticker

6/recent/ticker-posts

Definiciones de API estándar desmitificadas


 Al igual que con cualquier industria, el espacio de API web enfrenta diferentes enfoques de estandarización. Entre las que destacan las diferencias entre la forma en que los proveedores de API eligen definir sus API de forma legible por máquina con especificaciones de API y lenguajes de descripción.

Las definiciones de API han surgido como formas de anotar funcionalidades de API, y todavía hay muchas que se adaptan a diferentes arquitecturas de servicios web. Al trabajar con diferentes lenguajes como JSON, YAML, Markdown, RAML o WADL, las definiciones de API pueden ser una herramienta poderosa para cosas como generar documentación interactiva o pruebas de API.

Si bien muchos usuarios experimentados entienden las sutilezas entre las terminologías en nuestro ámbito, esto crea una especie de barrera de entrada para aquellos que no son desarrolladores a largo plazo o evangelistas de API veteranos. Esto es siempre importante cuando discutimos las formas comunes en que se describen las interfaces de programación de aplicaciones .

Hoy, vamos a describir algunas de las definiciones de API más utilizadas , viendo cómo se usa cada una y dónde encajan en la caja de herramientas del proveedor de API. Si bien no cubriremos todas las definiciones jamás creadas, nuestra lista proporcionará una sólida introducción a los diferentes enfoques de especificación de API, sus lenguajes de descripción elegidos y su importancia dentro de la industria.

Relacionado: ¿Cuál es la diferencia entre documentación, especificación y definición de API?

6 tipos de especificaciones de API comunes

Primero, comenzaremos enumerando las especificaciones y los lenguajes de descripción más comunes para las API web.

Especificación OpenAPI / Swagger

Especificación de OpenAPI : la especificación de OpenAPI, formalmente conocida como Swagger, es una especificación popular y una implementación de marco diseñada para ser legible tanto por humanos como por máquinas. Debido a que la Especificación OpenAPI es simplemente el nuevo nombre del proyecto Swagger y sus diversas actualizaciones, esta definición se superpone con Swagger.

Swagger : Swagger es una especificación de marco de API basada en JSON que está diseñada para ser legible tanto por máquinas como por humanos. La especificación Swagger se utiliza para crear una interfaz RESTful que mapea los recursos y las operaciones inherentes a la API, lo que permite una fácil detección sin la necesidad de acceder al código fuente o documentación adicional.

Si bien la definición técnica de Swagger se centraría principalmente en este marco, Swagger también se usa para referirse a la colección de recursos que se relacionan con él. El Swagger Editor, por ejemplo, permite la creación de una definición de Swagger para vincularla con la herramienta Swagger Codegen para generar implementaciones de servidor, que luego se pueden explorar a través de la herramienta de exploración Swagger UI.

Si bien las versiones 1.0 a 1.2 todavía son compatibles con muchos proveedores, la mayoría se está moviendo hacia la 2.0 compatible con JSON y YAML, que se conoce por su nombre rebautizado de OpenAPI Specification.

Swagger es independiente del lenguaje, y varios desarrolladores lo extienden a derivaciones y soluciones de especificación de lenguaje que admiten Scala, HTML5, Java, Actionscript 3 y otros. Esta amplia base es parte de lo que impulsó la transición al reposicionamiento como "Especificación OpenAPI", ya que la solución es extremadamente extensible y está abierta a la mutación.

Ejemplo de Swagger de los tutoriales de Apiary :

swagger: '2.0'
info:
  title: Polls Swagger
  description: Polls is a simple API allowing consumers to view polls and vote in them.
  version: "8234aab51481d37a30757d925b7f4221a659427e"
host: polls.apiblueprint.org
schemes:
  - https
paths:
  /questions:
    x-summary: Questions Collection
    x-description: ''
    get:
      summary: List all questions
      responses:
        200:
          description: 'List'
          examples:
            application/json:
              - question: "Favourite programming language?"
                published_at: "2015-08-05T08:40:51.620Z"
                choices:
                  - choice: "Swift"
                    votes: 2048
                  - choice: "Python"
                    votes: 1024
                  - choice: "Objective-C"
                    votes: 512
                  - choice: "Ruby"
                    votes: 256
Leer más sobre la iniciativa OpenAPI

RAML

RAML
 : RAML es un lenguaje de modelado diseñado específicamente para admitir tanto la documentación de API REST como aquellos que no se adhieren estrictamente a los estándares REST, como los que se basan en arquitecturas SOAP o RPC. Esto hace que RAML sea muy poderoso, lo que permite a los desarrolladores aprovechar marcos ampliamente modificados y otras soluciones no diseñadas en el enfoque REST clásico.

Sin embargo, no se equivoque: RAML sigue siendo un enfoque de documentación orientado a REST.

RAML deriva su forma y función de YAML, un formato de serialización de datos de análisis diseñado para la legibilidad humana y de máquina, evitando el formato JSON casi omnipresente. RAML es una especificación de arriba hacia abajo, que documenta el comportamiento de cada elemento dentro del sistema mayor de arriba a abajo.

Debido a su diseño y filosofía, RAML se puede utilizar como mucho más que un simple enfoque de documentación, y de hecho se ha utilizado con gran efecto como un sistema de planificación de API a largo plazo. RAML puede generar respuestas simuladas, rastrear rutas de funciones e implementar consolas API interactivas de forma nativa, lo que la convierte en una gran herramienta para la creación de prototipos y las pruebas en vivo.

Ejemplo extraído de jukebox-api.raml del tutorial RAML 200 :

/songs:
  description: Collection of available songs in Jukebox
  get:
    description: Get a list of songs based on the song title.
    queryParameters:
      songTitle:
        description: "The title of the song to search (it is case insensitive and doesn't need to match the whole title)"
        required: true
        minLength: 3
        type: string
        example: "Get L"
    responses:
      200:
        body:
          application/json:
            example: |
              "songs": [
                  {
                    "songId": "550e8400-e29b-41d4-a716-446655440000",
                    "songTitle": "Get Lucky"
                  },
                  {
                    "songId": "550e8400-e29b-41d4-a716-446655440111",
                    "songTitle": "Loose yourself to dance"
                  },
                  {
                    "songId": "550e8400-e29b-41d4-a716-446655440222",
                    "songTitle": "Gio sorgio by Moroder"
                  }
                  ]
...
Consulte nuestra lista de más de 30 soluciones de documentación de API

Proyecto API

API Blueprint : API Blueprint es una especificación de arriba hacia abajo, que explica el comportamiento de varios subcomponentes y divide la API como método de documentación. API Blueprint utiliza Markdown , un conocido lenguaje de marcado ligero entre los desarrolladores y autores web, para documentar las API.

A diferencia de RAML y Swagger, API Blueprint no proporciona su propio método para generar código de servidor y, en cambio, se basa en integraciones de terceros para hacerlo. Además, API Blueprint utiliza C ++ a través de Node.js y C # en lugar de utilizar Java y js como lo hacen RAML y Swagger.

API Blueprint carece de varias características importantes, como construcciones avanzadas y herramientas a nivel de código, pero sigue siendo una implementación poderosa cuando se usa en el caso de uso correcto.

Ejemplo tomado de la API de CloudApp , descrito en API Blueprint:

FORMAT: 1A
HOST: http://api.cl.ly/

# CloudApp API


## Collection [/v3/collection]

### Fetch collection [GET]

+ Response 200 (application/json)

        {
            "data": [
                { "id": 1, links: [] },
                { "id": 2, links: [] }
            ],
        
            "links": {
                "next_page": {
                    "href": "/v3/collection?after=12345678",
                    "method: "GET"
                }
            }
        }
...

Mashery y documentos de E / S

I / O Docs : I / O Docs, desarrollado por Mashery, es un sistema de documentación interactivo para las API RESTful. Al definir las API "a nivel de recursos, métodos y parámetros en un esquema JSON", I / O Docs genera interfaces de cliente JavaScript de forma dinámica, que se pueden utilizar para ejecutar llamadas.

I / O Docs fue desarrollado por Mashery , propiedad de TIBCO , una empresa de administración y servicios de API cuyo enfoque se extiende más allá de la documentación y en la creación y administración de servicios web.

I / O Docs es un conjunto de herramientas en constante evolución: después de haber sido comprado primero por Intel y luego por Tibco, I / O Docs y todo el ecosistema y servicio de Mashery ha crecido exponencialmente. Si bien hubo quejas iniciales sobre la falta de funciones, I / O Docs ha evolucionado para admitir referencias, definiciones de autenticación extensibles, JSON serializado y más.

Ejemplo de la definición de documentos de E / S de la guía de configuración de documentos de E / S de Mashery :


{
 "name": "Example #1 API",
 "version": "1.0",
 "title": "The Key Only Auth API",
 "description": "The first example features API key based authentication only.",
 "protocol": "rest",
 "basePath": " http://api.example1.com/v1",
 "auth": {
 "key": {
 "param": "api_key",
 "location": "query"
 }
 },
 "resources": {
 "Product Methods": {
 "methods": {
 "Get Products": {
 "path": "/products.:format",
"httpMethod": "GET",
"description": "Get all products in our database",
"parameters": {
 ":format": {
 "type": "string",
"required": true,
"default": "json",
"description": "Output format as JSON or XML",
"enum": [
 "json",
 "xml"
 ],
"location": "pathReplace"
 }
 }
 }
 }
 }
 }
}

Servicio de descubrimiento de API de Google

Servicio de detección de API de Google : el servicio de detección de API de Google es el método de Google para crear metadatos legibles por máquina sobre las API de Google y también actúa como un sistema para crear bibliotecas cliente, complementos y otro contenido para las API de Google. La API Discover en sí se basa en JSON y está diseñada para ser legible por máquina.

El documento de Google Discovery describe este tipo de metadatos. Ejemplo :

  "kind": "discovery#restDescription",
  "name": "urlshortener",
  "version": "v1",
  "title": "Lets you create, inspect, and manage goo.gl short URLs",
  "description": "Lets you create, inspect, and manage goo.gl short URLs",
  "protocol": "rest",
  "basePath": (Deprecated) "/urlshortener/v1/",
  "rootUrl": "https://www.googleapis.com/. Root URL under which all API services live",
  "servicePath": "/urlshortener/v1/. Base path for all REST requests",
…

WADL (W3C 2009)

WADL (W3C 2009) : WADL, o Lenguaje de descripción de aplicaciones web, es un lenguaje que describe aplicaciones web basadas en HTTP en un formato legible por máquina.

WADL se desarrolló para reemplazar un área de documentación que a menudo se pasa por alto. Si bien la documentación de texto o wiki simple junto con un documento de esquema es adecuada para lectores humanos, esto a menudo debe convertirse o analizarse en formatos legibles por máquina (o una nueva documentación generada en un formato legible por máquina), lo que aumenta la dificultad para comprender y aprovechar.

Por lo tanto, WADL se enfoca en representar los recursos, relaciones, métodos y formatos detrás de los datos en una API de una manera que pueda ser entendida, explicada y aprovechada por máquinas sin una capa de traducción secundaria.

La documentación oficial de WADL menciona varios casos de uso que destacan por qué esto es necesario. Los procesos como el modelado y visualización de aplicaciones, la generación de código y la configuración de clientes y servidores no suelen tener un elemento humano directo que trabaje detrás de escena; en consecuencia, cuando se introduce un lenguaje legible por humanos, debe traducirse a legible por máquina.

Otras menciones honoríficas

Formato APIMATIC

El formato APIMATIC es el formato de entrada predeterminado para APIMATIC. APIMATIC es un proveedor de soluciones de gestión de plataformas SDK que cuenta con varias características clave como parte de su literatura.

En primer lugar, promueven la generación de SDK personalizados sobre una metodología basada en la nube. Además, prometen escalabilidad e integración dentro de una variedad de pilas de programación. Estas características y más se utilizan como un conjunto de herramientas para generar lo que APIMATIC llama "SDK simples que sus equipos de desarrollo adorarán".

HAR 1.2

HAR 1.2 : HAR 1.2 Spec, también conocido como HTTP Archive Spec, es un formato utilizado por las herramientas de supervisión y alaytics HTTP para exportar datos. HAR fue diseñado para ser flexible para la maleabilidad entre proyectos y para la compatibilidad entre varias herramientas, lo que permite un procesamiento y análisis más efectivos.

El formato se basa formalmente en JSON. HAR utiliza codificación UTF-8 y representa datos en una variedad de tipos de objetos como "páginas", "contenido" y "tiempos".

Es interesante que HAR tiene la ventaja de ser desarrollado e implementado por el World Wide Web Consortium , también conocido como W3C. El W3C es el principal organismo de estándares para la World Wide Web y, por lo tanto, HAR se considera generalmente, una vez completado, un sistema universal para el formateo de datos de este tipo.

Sin embargo, vale la pena mencionar que, a diferencia de otras entradas de esta lista (como la especificación OpenAPI, que es un cambio de marca de un sistema anterior, Swagger), HAR 1.2 todavía se encuentra en la fase de borrador .

ML rápido

Rapid-ML : RAPID-ML es un enfoque para el diseño de API que se centra principalmente en el modelado de datos. Describe los tipos de datos utilizando un lenguaje “independiente de la tecnología” y, a menudo, se comercializa como una forma de “integrar más rápido” y “liberar […] a los desarrolladores de clientes de la discrepancia de API”.

Rapid-ML maneja esto usando generadores de esquemas JSON y XML que se vinculan con modelos de datos compartidos de máquinas locales o repositorios http, y usan recursos y parámetros vinculados en la API para validar y generar código.

Uno de los grandes puntos de venta de Rapid-ML es la idea de mostrar, usar y comprender las estructuras de datos referenciadas como un hipervínculo, una estructura integrada o ambas. Al hacer esto, en teoría, los viajes de ida y vuelta se optimizan y el ancho de banda de datos se reduce (aunque si esto realmente sucede en la práctica está determinado por muchas más variables además de Rapid-ML.

Conclusión

Tenga en cuenta que este no es un recurso completo; ciertamente ha habido otros intentos de construir especificaciones API y metadatos legibles por máquina para estandarizar la forma en que definimos las API. Dicho esto, esto representa la mayor parte de los tipos de especificación de API más comunes que encontrará actualmente en todo el panorama de API moderno. Ahora, en términos de cuál usar, exploraremos algunos con más detalle en el futuro. Por supuesto, con un impulso tan grande en el proyecto de API abierta y la comunidad de herramientas circundante, es muy posible que esta lista se reduzca drásticamente pronto.

Publicar un comentario

0 Comentarios