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.
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
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
RAML
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"
}
]
...Proyecto 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 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
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.
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
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 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.
0 Comentarios
Dejanos tu comentario para seguir mejorando!