Header Ads Widget

Ticker

6/recent/ticker-posts

Diseño de API evolucionables para la web: identificación

 

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

La relevancia comercial y técnica actual de las API web es visible y documentada en un número cada vez mayor de artículos, productos y conferencias. Sin embargo, estos esfuerzos se han centrado principalmente en el lado de la API (Interfaz de programación de aplicaciones) y menos en la Web .

Este artículo es el primero de una serie que tiene como objetivo volver a centrar la atención en la Web, en su arquitectura subyacente y en lo que significa crear API evolutivas para ella. Abordamos no solo las tecnologías que construyen la Web, sino también los principios arquitectónicos fundamentales que guiaron el desarrollo de estas tecnologías.

Como veremos, la arquitectura web es perfectamente adecuada para exponer API. Sin embargo, tiene algunas características no obvias que conviene tener en cuenta si queremos aprovechar al máximo lo que ofrece la Web.

Presentación de los 3 pilares de la Web

3-pilares-de-la-web-nordic-apis-pedro-felix

El documento " Arquitectura de la World Wide Web, Volumen uno " ayuda a definir los recursos y describe los tres pilares arquitectónicos de la Web:

  • Identificación : todos los recursos se identifican globalmente mediante URI (identificadores uniformes de recursos).
  • Interacción : los agentes web interactúan a través del intercambio de mensajes, es decir, mensajes HTTP.
  • Formatos : los mensajes intercambiados transmiten información basada en formatos predefinidos.
Pilares arquitectónicos de la Web

Pilares arquitectónicos de la Web

En esta serie, ampliamos cada pilar de esta base arquitectónica central y su relevancia para las API web. En este artículo específico, nos centraremos en definir la Identificación y nos aventuraremos en Interacción y Formatos en las siguientes publicaciones.

Definición de tipos de recursos

Nuestro viaje comienza en un documento bastante antiguo (y quizás no muy conocido), titulado “ Arquitectura de la World Wide Web, Volumen uno ”, escrito por el Consorcio World Wide Web en 2004. Este documento comienza diciendo:

La World Wide Web (WWW, o simplemente Web) es un espacio de información en el que los elementos de interés, denominados recursos, se identifican mediante identificadores globales denominados Identificadores Uniformes de Recursos (URI).

Recursos

Recursos

Esta oración presenta dos características importantes de la Web. Primero, la Web es un espacio de información y no solo un conjunto de páginas, lo que la hace muy aplicable a las API que interactúan con la información. En segundo lugar, los elementos que componen este espacio se denominan recursos . El concepto de recurso es fundamental para la arquitectura web, sin embargo, su caracterización puede no ser obvia.

Los tipos de recursos o "elementos de interés" son variados. Para una API como la proporcionada por GitHub , estos elementos serán repositorios, confirmaciones, sucursales, problemas, usuarios, organizaciones, etc. En un sistema de IoT (Internet de las cosas) , los elementos probablemente serán sensores y actuadores.

Leer: Enfrentamiento de microservicios: REST vs SOAP vs Apache Thrift

Identificación: URI vs URL

Cada recurso web se identifica mediante al menos un identificador global y uniforme , llamado URI . En la Web, un URI identifica de forma inequívoca un solo recurso , sin necesidad de contexto adicional.

Identificación

Identificación

La propiedad global de este sistema de identificación proviene del hecho de que no se requiere más información, aparte del URI, para identificar un recurso. Esto contrasta con los identificadores locales que solo son significativos si se les da un contexto adicional. Por ejemplo, el identificador 1234567probablemente no sea suficiente para identificar y ubicar una entrada en una base de datos relacional. Sin embargo, dada la información adicional de que es un identificador de factura, probablemente ahora podamos acceder a la factura a select * from invoices where id = '1234567'través de una GetInvoiceByIdoperación.

Un tipo especial de URI llamado Universal Resource Locator (URL) proporciona aún más información: las URL son suficientes para interactuar con el recurso que identifican. Por ejemplo, una URL "http" es suficiente para obtener una representación del estado del recurso identificado a través de una solicitud HTTP GET.

En lugar de identificadores locales de recursos (p 1234567Ej. ) Y operaciones (p GetInvoiceByIdEj. ), La Web nos proporciona identificadores globales (p Ej. ) Y operaciones de interacción genéricas (p. Ej., Método HTTP ).https://api.example.com/invoices/1234567GET

Definición de estructura y sintaxis de URI / URL

La sintaxis de URI generalmente se define en RFC 3986 como:

URI         = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

Para el caso particular del esquema "http" (y "https"), definido en RFC 7230 , la sintaxis se convierte en:

http-URI = "http:" "//" authority path-abempty [ "?" query ] [ "#" fragment ]

La definición de la estructura de la URL es una de las tareas necesarias al diseñar una API web y se rige por varios requisitos. Primero, debemos asegurarnos de que una URL codifique toda la información necesaria para identificar completamente el recurso de destino, incluidos los identificadores locales, como el número de factura o el número de línea de la factura. Si el recurso representa una colección, también se debe incluir información adicional como la paginación y los criterios de filtrado y clasificación.

Tenga en cuenta que la misma colección filtrada u ordenada por un criterio diferente son recursos diferentes . Por ejemplo, las URL identifican dos recursos distintos. No es adecuado interpretar estas dos URL como la misma URL con diferentes parámetros, es decir, porque la cadena de consulta es un componente integral de la URL y no solo un decorador sobre ella. Dado que otros componentes, como los intermediarios de almacenamiento en caché, se basan en estos detalles, la distinción no es solo una pedantería superflua.https://api.example.com/customer/123/invoices?sort=datehttps://api.example.com/customer/123/invoices?sort=amount

Una pregunta típica que surge al diseñar la estructura de la URL es qué incluir en la ruta frente a qué incluir en la cadena de consulta . Teniendo en cuenta que ambos son componentes de URL, la respuesta proviene de la distinción establecida en RFC 3986 , que describe la sintaxis de URI:

El componente de ruta contiene datos, generalmente organizados en
forma jerárquica , que, junto con los datos del componente de consulta no jerárquica
(…), sirven para identificar un recurso (…)

Esto significa que la ruta debe usarse para representar información que tenga alguna relación jerárquica . Por ejemplo, la API de GitHub usa la ruta para codificar el propietario del repositorio, el nombre del repositorio y el número de problema al identificar un solo comentario de problema.

https://api.github.com/repos/webapibook/issuetracker/issues/1

Por otro lado, los datos no jerárquicos, como los criterios de clasificación y filtrado, generalmente se incluyen en la cadena de consulta, utilizando pares de nombre y valor. Como ejemplo, la API de GitHub usa la cadena de consulta para codificar las palabras clave de búsqueda, el campo de clasificación y el orden de clasificación en su API de búsqueda.

https://api.github.com/search/repositories?q=user:webapibook&sort=issues&order=desc

Sin embargo, tenga en cuenta que esta estructura de nombre-valor utilizada en la parte URI de la cadena de consulta no es obligatoria por el RFC 3986. Es un uso muy común, popularizado por la especificación HTML que usa este formato, nombrado application/x-www-form-urlencodedpara representar el conjunto de datos del formulario. La estructura de la URL también debe diseñarse para que sea fácil de manejar en el lado del servidor. Desafortunadamente, esto depende del marco concreto del servidor HTTP, es decir, su motor de enrutamiento, por lo que es difícil proporcionar reglas generales aquí. Sin embargo, se debe tener especial cuidado para permitir la evolución de la API al permitir que se identifiquen nuevos tipos de recursos sin crear ambigüedades.

Descarga nuestra guía de desarrollo gratuita

Sobre legibilidad de URL

Especialmente en el ámbito de las API, se debe considerar la legibilidad de URL , ya que facilita el procesamiento de URL para los humanos . Por ejemplo, el significado de es mucho más fácil de entender que , es decir, cuando se observan trazas de registros.https://api.example.com/customer/123https://api.example.com/2335bbb6-8e33-4f88-8088-03d996f52752

Toda esta discusión sobre el diseño de la estructura de la URL es principalmente relevante solo para el lado del servidor. Para los clientes, las URL son en su mayoría opacas, como se indica en las mejores prácticas en " Arquitectura de la World Wide Web, Volumen uno ".

Buena práctica: opacidad URI

Los agentes que hacen uso de URI NO DEBEN intentar inferir las propiedades del recurso al que se hace referencia.

Es decir, los clientes no deben depender de una estructura de URL específica, sino que deben usar las URL tal como las proporciona el servidor mediante controles hipermedia . (Abordaremos los hipermedia en un próximo artículo de esta serie).

En el caso de que el cliente deba proporcionar parte de la información para codificar una URL, la API web debe usar plantillas de URI , como Esta sintaxis de plantilla está definida por RFC 6570 (Plantilla URI) y en este ejemplo informa al cliente que la variable debe expandirse en la cadena de consulta. El cliente debe proporcionar la variable para expandir la plantilla de URI en una URL. Esto significa que lo más probable es que el cliente, o el usuario en cuyo nombre actúa, sepa que unhttps://api.example.com/customer/123/invoices{?sort}sortsortsortexiste una variable, y también comprender la semántica y los posibles valores que se pueden ingresar. Sin embargo, dado que la estructura de la URL no está codificada en el lado del cliente, puede evolucionar sin romper a los clientes. Como ejemplo, GitHub usa plantillas de URI en su recurso raíz: https : // api github com , es decir, para describir la estructura y el método necesarios para realizar búsquedas.

"code_search_url": "https://api.github.com/search/code?q={query}{&page,per_page,sort,order}",

Los {&page,per_page,sort,order}medios que la cadena de consulta acepta cuatro teclas opcionales: pageper_pagesortorder.

Conclusión: use plantillas de URI para la evolución

Como veremos varias veces a lo largo de esta serie, la interacción entre el cliente y los servidores siempre requiere algún tipo de contrato. Sin embargo, la forma en que se definen estos contratos determina la capacidad de evolución de la interacción. El uso de plantillas de URI no elimina el conocimiento a priori requerido en el lado del cliente, sin embargo, permite que el servidor cambie la estructura general de URI.

Con esto finaliza nuestro primer artículo de la serie, en el que nuestro objetivo es volver a poner el foco de las API web en la Web, en su arquitectura subyacente y en lo que significa crear API evolutivas para ella. En el siguiente artículo analizaremos el segundo pilar de la Web: la interacción . Suscríbase a nuestro boletín para asegurarse de no perderse las próximas publicaciones de esta serie.

Diseño de API evolucionables para la serie web

  

Publicar un comentario

0 Comentarios