Header Ads Widget

Ticker

6/recent/ticker-posts

Negociación de contenido para la longevidad de la API web

 

negociación-de-contenido-REST-API-longevidad-nordic-apis

De vez en cuando, aparece un nuevo formato de archivo de imagen que comprime mejor las imágenes que JPEG o PNG. Hemos visto a Google impulsando su propio formato Webp (supuestamente un 26% más pequeño en tamaño en comparación con PNG), y los nuevos formatos BPG y FLIF son contendientes, empaquetando imágenes en cada vez menos espacio y tiempo que sus predecesores.

Además de la compresión, la experiencia del usuario se está mejorando con SVG, un formato vectorial adecuado para pantallas retina. Los GIF animados se han disparado en popularidad, ahora están presentes en demasiados memes y están disponibles en la mayoría de las aplicaciones de mensajería. Imgur ahora es compatible con GIFV , una alternativa de video. Es evidente que es probable que sigan surgiendo nuevos formatos de imagen y que su uso cambie en los próximos años. La misma alta volatilidad hacia el cambio se aplica a todos los tipos de medios .

Con eso en mente, ¿cómo podemos diseñar API duraderas que se adapten a un mundo de formatos de archivo en constante cambio ? Según Erik Michaels-Ober de Soundcloud , la respuesta del millón de dólares es la negociación de contenido , una técnica que ha existido durante décadas, pero que sorprendentemente no ha sido adoptada por muchas API REST que sirven datos estructurados o medios.

¿Qué es la negociación de contenido?

"HTTP tiene disposiciones para varios mecanismos de" negociación de contenido ", el proceso de seleccionar la mejor representación para una respuesta determinada cuando hay varias representaciones disponibles".
RFC 2616 Fielding

La negociación de contenido permite al usuario determinar qué tipos de medios prefiere recibir del servidor. Es un mecanismo definido en el protocolo HTTP ( RFC 7231 ), lo cual es genial, porque las API REST funcionan junto con HTTP.

El ejemplo más común de negociación de contenido es el comportamiento navegador-servidor. Digamos que se ha programado un navegador para privilegiar el sueco sobre el inglés y, si ninguno de los dos está disponible, para ofrecer el danés. El Acceptencabezado se verá así:

Accept-Language: sv; q=1.0, 
en; q=0.7, 
da; q=0.5

Accept: text/html; q=1.0, 
text/*; q=0.8, 
image/gif; q=0.6, 
image/jpeg; q=0.4, 
image/*; q=0.3, 
*/*; q=0.1

Los navegadores pueden enviar información como parte de cada solicitud sobre las representaciones que prefieren, con factores q para indicar la preferencia de uso en relación con otros idiomas, formatos de texto y tipos de imágenes. Entonces, el servidor responde de la mejor manera posible a estas necesidades. El agente de usuario también puede solicitar que se sirva un formato de datos específico desde un servicio web, como application/jsonapplication/xml.

Relacionado: Consulte nuestra serie Designing Evolvable APIs for the Web

Estado del diseño de API

Muchos tienden a ver las API RESTful como una mejor opción de diseño que SOAP. Aunque hay casos comunes en los que el uso de SOAP tiene sentido , REST como estilo arquitectónico tiene mucha credibilidad, diseñado por Roy Fielding , el creador de HTTP, que es el protocolo más exitoso jamás inventado.

En el espíritu de diseñar API duraderas, REST es posiblemente mejor que SOAP para la distribución de contenido . Tome las diferentes formas de recuperar un solo recurso.

Con SOAP , todos los datos se almacenan en el cuerpo XML, por lo que una POSTsolicitud a /api.xmlaccedería al mismo punto final para cada solicitud. Este diseño descarta el URI (Identificador de recurso único) y agrupa todos los datos en un solo recurso. Luego, hay procedimientos remotos adicionales necesarios para acceder a un solo archivo de imagen. No es exactamente así como funciona la web de forma natural.

REST está diseñado específicamente para trabajar con HTTP. Dado que los recursos web están identificados por URI, las solicitudes GET se pueden realizar a puntos finales únicos. Una llamada a /users/avatar/nordicapis.pngpuede recuperar fácilmente un archivo de imagen. Este diseño es más simple, elimina la duplicación, los procedimientos remotos complejos y funciona con el protocolo HTTP de la forma prevista.

El caso para borrar extensiones de nombre de archivo

.txt, .doc., .rtf, .pdf, .jpeg, .gif, .png, .mp3, .wav: casi todos los sistemas operativos utilizan estas extensiones de nombre de archivo, pero ¿son completamente necesarias? En cierto modo, no, dentro de un entorno UNIX, si un programa es ejecutable o no está determinado por los permisos del archivo, no por la extensión. Esta capa adicional de complejidad, por costumbre, evolucionó hacia la web como una cuestión de estilo. Según Michaels-Ober, no deberíamos codificar estas extensiones de archivo en URI. A continuación, exploraremos algunos casos de por qué.

Aceptar la documentación HTTP del encabezado

El campo Accept request-header se puede utilizar para especificar ciertos tipos de medios que son aceptables para la respuesta. Los encabezados de aceptación se pueden utilizar para indicar que la solicitud se limita específicamente a un pequeño conjunto de tipos deseados, como en el caso de una solicitud de una imagen en línea.
Aceptar encabezado RFC

Tomemos un escenario en el que queremos recuperar la foto del avatar de un usuario. Como dice la RFC, puede especificar varios formatos que puede aceptar, solicitar un PNG se vuelve redundante. Si usamos un encabezado de aceptación, podemos eliminar el PNG del nombre del recurso y reemplazarlo con una lista de tipos de imágenes aceptables, con un factor q para determinar qué tan fuertemente preferimos un determinado formato en relación con otros.

GET /user/avatar/nordicapis.png

Accept: image/png,
	image/jpeg; q=0.8,
image/gif; q=0.8,
	image/*; q=0,5
	application/json; q=0.1

¿Qué pasa si hay una respuesta de error? Queremos la capacidad de devolver JSON y manejar el error en el lado del cliente. Dado que esta solicitud puede devolver JPEG, GIF e incluso JSON, tener un .png en el URI no tiene mucho sentido.

Digamos que la red social lanza nuevas funciones y ahora también admite avatares de video . Lo bueno es que el URI permanece constante, y ahora todo lo que el cliente tiene que hacer es decir que acepta videos en el encabezado HTTP accept.

GET /user/avatar/nordicapis

Accept: video/avi; q=0.8,
	video/mov; 8=0.5,
video/*,
	image/gif; q=0.8,
	image/*; q=0.5,
	application/json; q=0.1,

Esta es la negociación de contenido . El cliente dice qué es compatible, qué acepta y el servidor responde con los formatos de devolución relevantes, si están disponibles.

Entrega dinámica de formatos XML / JSON

Si su API devuelve una representación XML de un usuario, es posible que desee hacer referencia al mismo usuario en un formato completamente diferente; puede cambiar con el tiempo o según el cliente o dispositivo que acceda a él. Dos representaciones del mismo recurso (representaciones JSON / XML) deberían tener el mismo URI en aras de la longevidad, pero si los clientes tienen diferentes preferencias de formato, ¿cómo sabemos qué formato servir?

Si nos deshacemos de las extensiones de nombre de archivo y usamos un encabezado de aceptación, podemos eliminar las redundancias, reemplazando estas:

GET /users/nordicapis.json
GET /users/nordicapis.xml

Con este:

GET /users/nordicapis

Utilizando la información del encabezado de aceptación, se puede elegir automáticamente la representación más adecuada, según las preferencias del cliente.

Encabezado de aceptación de idioma

Aquí hay un ejemplo más práctico. Además, como se define en el RFC :

El campo de encabezado de solicitud Accept-Language es similar a Accept, pero restringe el conjunto de lenguajes naturales que se prefieren como respuesta a la solicitud.

Estamos acostumbrados a solicitar un índice, por lo general se especifica como esto: GET /index.se.htmlSin embargo, la mayoría de los navegadores ya envían un encabezado Accept-Language.

GET /index.se.html

Accept-Language: se

Nuevamente, no es necesario especificar esto en la URL. Mediante la negociación de contenido, las preferencias de idioma se pueden estipular en el encabezado Accept-Language:


Accept-Language: se, en-us; q0.8, en;q=0.7

Con este enfoque, no codificamos el idioma o el formato de los recursos en el URI, lo que tiene mucho sentido. El uso de un único /index/punto final elimina la duplicación y produce URL agradables, limpias y legibles. Dejar que los clientes especifiquen sus preferencias de esta manera también puede ayudar a mejorar el marketing con una documentación más limpia.

Razones del mundo real para adoptar la negociación de contenido

Los formatos de archivo cambian con el tiempo, lo que afecta la forma en que se distribuye el contenido en la web. Dado que las API lanzadas hoy pueden estar en los sistemas del cliente durante años ,  debemos implementar el diseño de negociación de contenido ahora para aumentar la longevidad.

Travis CI

TravisCI

¿Qué sucede si finalmente desea dejar de admitir un determinado formato de archivo? Cuando Travis CI actualizó la API de estado de su insignia a SVG, dejaron de servir un archivo PNG. Pero, para compatibilidad con versiones anteriores, se devolverá la versión SVG incluso si solicita PNG o SVG. Aquí está la locura de codificar formatos de archivo en el URI: cuando cambia la adopción de formato, puede terminar devolviendo un formato de archivo diferente al que se solicita técnicamente.

Formatos de Google

Webp-logo-nordic-apis

WebM y Webp son formatos de archivo alternativos que Google ha impulsado. Aunque Google admite los formatos dentro de sus propias aplicaciones, realmente no han despegado con demasiada fuerza en entornos de terceros. Sin embargo, es difícil minimizar la influencia que tiene un gigante como Google en la economía web. Si algún formato nuevo se pone de moda, necesitará una forma de hacer evolucionar su API de contenido.

Gorjeo

logotipo de twitter plano

En junio de 2014, Twitter comenzó a admitir GIF animados. En 2015, los GIF también se adoptaron en las cargas útiles de JSON. La forma en que lo admiten es tomando un GIF y convirtiéndolo en un video (Mp4) para obtener beneficios de compresión. Otro ejemplo más de la evolución del formato en una plataforma de API de confianza.

Diseño de software a escala de décadas

No hace mucho tiempo que PNG era el nuevo formato de moda, elogiado por su compresión sin pérdidas. En los próximos años, podremos decirle adiós al tipo de archivo en favor de los SVG vectoriales cristalinos. Un cambio similar también ocurrirá inevitablemente en el texto: JSON ha usurpado XML en popularidad, y en el futuro, JSON podría ser reemplazado a favor de otro formato, como EDN , una alternativa extensible a JSON con más tipos base.

Con los pronósticos establecidos para una mayor fluctuación del formato de archivo (¡aliteración!), Debemos diseñar nuestras API como evolutivas desde el principio si queremos que resistan la prueba del tiempo. Esto significa exponer recursos , no representaciones, y no codificar el formato de archivo en la URL . Según Rob Zazueta de Mashery, un enfoque de negociación de contenido podría incluso reemplazar el control de versiones API tradicional .

REST es diseño de software a escala de décadas: cada detalle está destinado a promover la longevidad del software y la evolución independiente. Muchas de las limitaciones se oponen directamente a la eficiencia a corto plazo. Desafortunadamente, la gente es bastante buena en el diseño a corto plazo y, por lo general, pésima en el diseño a largo plazo. La mayoría no cree que sea necesario diseñar más allá de la versión actual.
Roy Fielding

¿Qué está haciendo su equipo para diseñar API web "a escala de décadas"?

Publicar un comentario

0 Comentarios