Header Ads Widget

Ticker

6/recent/ticker-posts

Diseño de API evolucionables para la web: formatos

Diseño-de-apis-evolutivas-para-formatos-web

Este es el tercer artículo de una serie que tiene como objetivo volver a poner el foco de las API web en la Web, en su arquitectura subyacente y en lo que significa construir API evolutivas para ella. En este primero presentamos la arquitectura de la Web junto con su primer pilar - Identificación . El segundo artículo y el anterior se centró en el segundo pilar: la interacción y el protocolo HTTP. Los presentes artículos terminan esta serie con un análisis del tercero - Formatos .

Otros artículos de la serie Designing Evolvable APIs for the Web :

El primer formato, y quizás el más frecuente, que se utiliza en la Web es HTML (lenguaje de marcado de hipertexto). Sin embargo, eso no significa que la Web y sus protocolos de interacción estén vinculados a un formato específico. Por el contrario, una de las características distintivas de HTTP es la capacidad de utilizar múltiples formatos para las representaciones transferidas. Esto contrasta claramente con la característica de "talla única" de SOAP de usar XML para todo. Esta elección de diseño tiene dos ventajas importantes.

Flexibilidad de formato

Primero, permite a los participantes de la Web elegir los mejores formatos para representar diferentes tipos de información. Por ejemplo, usar XML para representar una imagen comprimida es incómodo. Por otro lado, usar el formato JPEG para representar datos estructurados también estaría muy lejos de ser ideal.

En segundo lugar, el hecho de que la Web no dependa de un conjunto cerrado de formatos permite su evolución a través de la creación y adopción de nuevos formatos. Un ejemplo notable es la creación y amplia adopción del formato JSON para representar datos estructurados, reemplazando XML para muchos propósitos.

Sin embargo, esta independencia de formato no significa que los formatos sean un ciudadano de segunda clase de la Web o de un proceso de diseño de API Web. De hecho, es todo lo contrario. El protocolo HTTP define encabezados de metadatos específicos para transmitir tanto el formato utilizado (el Content-Typeencabezado de la entidad) como las preferencias de formato ( Acceptencabezado de la solicitud).

Estos encabezados utilizan identificadores de tipos de medios , como application/json, compuestos por un tipo de nivel superior (p applicationEj. ) Y un subtipo (p jsonEj .). Estos identificadores son administrados por IANA, la Autoridad de Números Asignados de Internet, que ejecuta un registro extensible con todos los formatos utilizables en la Web, así como sus identificadores, sintaxis y semántica. Un análisis rápido de los tipos de medios presentes en este registro muestra la riqueza de formatos disponibles actualmente.

Lea también: ¿Cómo conecta a todas las empresas del mundo?

Flexibilidad de formato en el ámbito de las API

Esta flexibilidad de formato también se aplica a las API web, que no necesitan restringirse al uso de representaciones basadas en JSON. Por ejemplo, si el procesamiento principal del cliente es producir una versión impresa de la información, podría ser perfectamente adecuado que una API web utilice una representación basada en PDF.

Incluso cuando se utilizan representaciones basadas en JSON, las API web deben evitar la creación y proliferación de formatos ad-hoc y, en su lugar, aprovechar formatos más específicos. Un gran ejemplo es el borrador de la especificación de Detalles del problema para las API HTTP , que define una forma legible por máquina de representar los detalles del error en una respuesta HTTP. El siguiente ejemplo, tomado de ese borrador de especificación, ilustra el uso de este nuevo formato para transmitir información sobre una solicitud con información no válida.

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Language: en

{
    "type": "https://example.net/validation-error",
    "title": "Your request parameters didn't validate.",
    "invalid-params": [ 
        {
            "name": "age",
            "reason": "must be a positive integer"
        },
        {
            "name": "color",
            "reason": "must be 'green', 'red' or 'blue'"
        }
    ]
}

Aprovechar estos formatos emergentes presenta múltiples beneficios para el diseñador y desarrollador de API web. Primero, proporcionan diseños razonables y bien diseñados para problemas comunes, basados ​​en implementaciones del mundo real y contribuciones de expertos. Lo más probable es que una solución ad hoc no sea tan robusta y evolutiva como estos diseños. En segundo lugar, al usar formatos comunes, los desarrolladores aprovechan las bibliotecas de código existentes para manejarlos.

La Web no es solo un conjunto de recursos desconectados. Son las conexiones entre los recursos, los enlaces, las que hacen que la Web merezca el nombre que tiene.

6.hipermedia

Los enlaces están presentes en representaciones y brindan al cliente información sobre cómo y cuándo interactuar con los recursos relacionados, identificados por sus URI. Por ejemplo, una representación HTML de un recurso normalmente contiene:

  • Vínculos a recursos externos que deben estar incrustados en el documento HTML, como extractos de Javascript y hojas de estilo CSS, que se siguen antes de que se procese la página.
  • Vínculos a recursos relacionados (por ejemplo, aelementos HTML), seguidos cuando se seleccionan los elementos de anclaje.
  • Formularios que desencadenan interacciones con otros recursos, basados ​​en información proporcionada por el usuario (por ejemplo, formelementos HTML).

Más precisamente, un enlace es una conexión escrita entre dos recursos y se define por:

  • el recurso de contexto , definido implícitamente por la representación donde se produce el enlace;
  • el recurso de destino , identificado explícitamente por un URI;
  • el tipo de relación , definiendo el tipo de conexión;
  • otros atributos de destino , como el método de interacción HTTP que se debe utilizar al activar el enlace.

RFC 5988 (Web Linking) define un conjunto de tipos de relación comunes, tales como firstnextselfupeditIANA mantiene un conjunto más completo de relaciones de enlace en su registro de relaciones de enlace . RFC 5988 también define una forma de definir enlaces en los metadatos de representación, y no en la representación en sí, a través del Linkencabezado de entidad HTTP. Un ejemplo de esta característica es la información de paginación que devuelve la API de GitHub .

Enlace: < https : // api . github . com / user / repos ? página = 3 & por _ página = 100 >; rel = "siguiente",
< https : // api . github . com / user / repos ? página = 50 & por _ página = 100 >; rel = "último"

Observe el uso de las relaciones de enlace nextlastdefinidas por RFC 5988. El encabezado de enlace es particularmente útil cuando se utilizan enlaces con formatos que no los admiten de forma nativa y que no se pueden ampliar fácilmente, como los formatos de imagen.

Tipos de hipermedia para API web

Por otro lado, los formatos, como HTML, que contienen soporte nativo para representar enlaces, se denominan tipos hipermedia . En el ámbito de las API web, desafortunadamente, el formato JSON predominante no es un tipo hipermedia porque no proporciona de forma nativa formas de representar enlaces.

Sin embargo, JSON proporciona suficiente extensibilidad para agregar esos enlaces en la parte superior de su modelo. Por ejemplo, la API de GitHub hace exactamente eso, utilizando *_urlpropiedades para representar enlaces (consulte https://developer.github.com/v3/#hypermedia )

Afortunadamente, recientemente ha habido propuestas más establecidas para crear formatos hipermedia basados ​​en JSON. En las siguientes secciones, examinaremos tres de los principales tipos de hipermedia emergentes: HAL, Siren y Collection + json.

Tipo de hipermedia HAL

Uno de los primeros tipos de hipermedia fue Hypermedia Application Language (HAL) , que ha sido adoptado por varias API, incluida la API REST de Amazon API Gateway . El siguiente extracto ilustra el uso de HAL para representar problemas y comentarios en un sistema de seguimiento de problemas ficticios:

{
    "_links": {
        "self": { "href": "/issues/123"},
        "author" : {"href”: “/users/pmhsfelix"}
    },
    "title": “NordicApi slides",
    "description": "Create slides for the Nordic APIs session",
    "_embedded": {
        "issues:comments": [
            {
                "_links": { 
                    "self": {"href" : "/api/issues/123/comment/1"}
                },
                "text": "don’t forget it’s only 25 minutes"            
            },
            {
                "_links": { 
                    "self": {"href" : "/api/issues/123/comment/2"}
                },
                "text": "finally done"   
            }
        ]                    
}}

Cada representación se define como un objeto JSON de nivel superior con la _linkspropiedad reservada que contiene un conjunto de enlaces. El valor de esta propiedad es un objeto, cuyos nombres de propiedad son relaciones de vínculo (por ejemplo, selfauthor) y los nombres de propiedad son objetos de vínculo o matrices de objetos de vínculo.

Un objeto de enlace representa un enlace a través de una hrefpropiedad obligatoria , con el identificador de destino del enlace y otras propiedades de enlace complementarias como titletypeEl estado del recurso está representado por un conjunto de propiedades personalizadas en el objeto raíz, como titledescriptionen el ejemplo anterior.

El formato HAL también tiene el concepto de representaciones integradas: representaciones parciales de recursos relacionados con la raíz. Estas representaciones están contenidas en la _embeddedpropiedad, cuyo valor es un objeto. Cada propiedad de este objeto representa una relación de enlace , y su valor es la representación parcial del recurso (s) que es el objetivo del enlace.

Antes de que un cliente utilice un enlace para realizar una solicitud, hay una serie de preguntas que deben responderse, a saber:

  • ¿Cuál debería ser el método de solicitud?
  • ¿La solicitud debe tener un cuerpo y, de ser así, cómo se debe construir?

Al usar HAL, el cliente solo tiene la relación de enlace para ayudar a responder estas preguntas, ya que no se proporciona ninguna otra información relevante. Esto significa que debe haber un contrato codificado que indique cómo se asigna cada relación de enlace a una solicitud.

Tipo de sirena hipermedia

Siren es otro tipo de hipermedia emergente que supera estas limitaciones al introducir el concepto de enlaces inseguros , llamados acciones, así como campos de acciones, similares a los campos de formulario HTML.
El siguiente extracto de JSON, tomado de https://github.com/kevinswiber/siren , ilustra cómo se representa una acción :

{
  "name": "add-item",
  "title": "Add Item",
  "method": "POST",
  "href": "http://api.x.io/orders/42/items",
  "type": "application/x-www-form-urlencoded",
  "fields": [
    { "name": "orderNumber", "type": "hidden", "value": "42" },
    { "name": "productCode", "type": "text" },
    { "name": "quantity", "type": "number" }
  ]
}

Observe cómo la acción define el método HTTP, el formato del cuerpo de la solicitud, así como sus campos constituyentes ( orderNumberproductCodequantity). Al hacer que esta información sea explícita en el control del enlace y no codificada en la relación del enlace, el tipo de medio Siren facilita la evolución de la API . Un ejemplo sería la adición de un nuevo campo, que puede expresarse dinámicamente en la propia información del enlace.

Colección + json Hypermedia Type

Finalmente, collection + json es otro tipo de hipermedia basado en JSON. Sin embargo, en lugar de ser de uso general, se diseñó específicamente para representar colecciones de elementos, así como para definir interacciones con estas colecciones. Es decir, define el soporte para lo siguiente:

  • plantillas de consulta : controles de vínculos que especifican cómo buscar colecciones.
  • plantillas de escritura : controles de enlaces que definen cómo agregar elementos a las colecciones.

Conclusión: Resumen de la serie de API web evolucionables

La definición de los formatos utilizados en una API web es una de las tareas fundamentales que enfrenta el diseñador de API. Tomar los objetos internos y usar un serializador JSON para exponerlos a través de HTTP casi nunca es una buena decisión, especialmente porque existen formatos más robustos. Aproveche la riqueza de formatos que está surgiendo en torno a las API web, a saber, formatos específicos para un propósito como problem + json y collection + json, así como formatos de propósito general como HAL y Siren.

La Web es un espacio de información global con un éxito, una escala y una capacidad de evolución sin precedentes. Muchas de estas características se derivan de sus principios arquitectónicos centrales . A lo largo de la serie Designing Evolvable APIs for the Web , hemos destacado estos principios; ahora aproveche este conocimiento para crear API que sean ciudadanos de primera clase de la Web.

Diseño de API evolucionables para la serie web

   

Publicar un comentario

0 Comentarios