Header Ads Widget

Ticker

6/recent/ticker-posts

Los beneficios de usar la API JSON


 

En el mundo de la artesanía API, no hay área que se discuta más acaloradamente que el diseño . Desde REST, gRPC hasta GraphQL, existen muchos enfoques para diseñar y estandarizar las interacciones API web. Hoy nos enfocamos en otro enfoque, JSON API , una especificación para construir API detallada en JSONAPI.org .

La API JSON, descrita en JSONAPI.org , es excelente para hacer que el formato de respuesta JSON sea más consistente. Con el objetivo de aumentar la productividad y la eficiencia, JSON API ha sido promocionada por sus eficientes funciones de almacenamiento en caché que pueden eliminar las solicitudes superfluas del servidor.

En este artículo, definiremos qué es la API JSON y veremos cómo se puede utilizar para crear API eficientes. Presentaremos algunos de los principales beneficios de la API JSON y también echaremos un vistazo a los estudios de casos de FitBit para ver cómo se ha utilizado esta especificación en la práctica. Con suerte, esta descripción general presentará a los recién llegados a la API JSON y lo ayudará a evaluar si es la adecuada para su escenario de API.

Vea la presentación de Jeremiah Lee sobre el uso de JSON API en la Cumbre de plataformas de 2017:

¿Qué es JSON API (JSONAPI.org)?

JSON API es un formato que funciona con HTTP . Delinea cómo los clientes deben solicitar o editar datos de un servidor y cómo el servidor debe responder a dichas solicitudes. Un objetivo principal de la especificación (ahora en una versión 1.0 estable ) es optimizar las solicitudes HTTP; tanto en términos del número de solicitudes como del tamaño de los paquetes de datos intercambiados entre clientes y servidores.

"JSON API es un protocolo de cable para obtener y actualizar de forma incremental un gráfico a través de HTTP"
Yehuda Katz

En la API JSON, tanto los clientes como los servidores envían datos de la API JSON en documentos de solicitud con el siguiente encabezado sin especificar los parámetros del tipo de medio:

Content-Type: application/vnd.api+json

La API JSON indica cómo se llaman los recursos y cómo se comparten los enlaces asociados . Un objeto JSON está en la raíz de las solicitudes, que deben incluir datos de recursos, error o metainformación. Los datos y también las relaciones con los datos se pueden recuperar a través de llamadas GET como estas:

GET /articles HTTP/1.1
Accept: application/vnd.api+json

Así es como puede aparecer un tipo de recurso "artículos" en una respuesta de la API JSON :

// ...
{ "type": "articles", "id": "1", "attributes": { "title": "Rails is Omakase" }, "relationships": { "author": { "links": { "self": "/articles/1/relationships/author", "related": "/articles/1/author" }, "data": { "type": "people", "id": "9" } } } } // ...

Hasta ahora, cosas bastante estándar. La API JSON es compatible con sus procesos CRUD típicos para crear, actualizar y eliminar recursos. La API JSON siempre será compatible con versiones anteriores y es una iniciativa impulsada por la comunidad que acepta solicitudes de extracción aquí en Github .

Beneficios del uso de la API JSON

Ahora que tenemos una idea básica de lo que es la API JSON, ¿cuáles son algunos de los beneficios únicos que la hacen destacar?

Documentos compuestos

Los documentos compuestos son una capacidad única en JSON API, que permite a los servidores enviar recursos relacionados junto con los recursos primarios solicitados; si se implementan correctamente, esto podría disminuir la cantidad de solicitudes HTTP necesarias. Los documentos compuestos funcionan utilizando el  parámetro de inclusión de la siguiente manera:

GET https://api.example.com/posts?include=author

Esto le permite incluir recursos adicionales en una solicitud inicial.

Conjuntos de campos dispersos

Si está utilizando documentos compuestos para incluir recursos relacionados, podría encontrarse con el problema de tener grandes respuestas . Una vez más, JSON API tiene una solución.

Otro aspecto único de la API JSON son los conjuntos de campos dispersos , que permiten a los clientes solicitar solo datos de campos específicos . Funciona agregando el campo que desea recuperar al parámetro URI con el nombre del recurso y los campos que desea. Esto ofrece personalización adicional y puede disminuir la hinchazón. Se parece a algo como:

GET /articles?include=author&;fields[articles]=title,body&;fields[people]=name HTTP/1.1
Accept: application/vnd.api+json

Los conjuntos de campos dispersos es un método estandarizado que permite a los clientes especificar solo las propiedades que desean de un objeto para que se incluyan en la respuesta. El uso de conjuntos de campos dispersos, se obtiene sólo los campos que usted desea, que ofrece el potencial de personalización único que se atractivo para magras entornos de intercambio de datos.

Leer también: Optimización de API para aplicaciones móviles

Opcionalidad

Muchas de las funciones de JSONAPI.org son puramente opcionales ; puede apagarlos o encenderlos. Las características dan a los clientes el poder de determinar qué recursos aceptar, prestando bien a entornos móviles ajustados. Hacer que los clientes se pongan de acuerdo sobre cómo recuperar y manejar los datos es útil, ya que elimina la redundancia y la optimización para reducir la hinchazón.

Funciones de optimización

La API JSON viene equipada con muchas funciones para optimizar el paquete de devolución de API . Las operaciones especiales del lado del servidor en la API JSON incluyen la clasificación , así como la paginación ; la capacidad de limitar el número de recursos devueltos a un subconjunto, con firstlastnext, y prevenlaces.

Almacenamiento en caché

En su presentación, Lee enfatizó cómo los recursos bien definidos pueden mejorar la capacidad de almacenamiento en caché, lo que resulta en un aumento en la "velocidad percibida" para los usuarios finales.

"Debido a que los cambios en los datos afectan a menos recursos, hay menos recursos invalidados cuando los datos cambian"

En los casos de uso de la API JSON, el almacenamiento en caché está esencialmente integrado en HTTP. Dado que los clientes que utilizan la API JSON acceden a los datos de la misma manera, no necesitan almacenar datos en varias ubicaciones. Este diseño puede requerir un cambio de pensamiento, pero si se usa correctamente puede traer importantes beneficios de optimización.

Relacionado: Cómo optimizar el paquete de respuesta API

Cómo se usa la API JSON en la práctica: estudio de caso de FitBit

Veamos cómo se ha implementado la API JSON en la práctica para diseñar API eficientes, utilizando FitBit como un caso de estudio de la vida real.

Jeremiah Lee dirigió el desarrollo de API en FitBit durante 4 años, tiempo durante el cual estuvo involucrado en la adopción de la API JSON. FitBit, la empresa de dispositivos portátiles de fitness, tiene un próspero programa de API; de 4 mil millones de solicitudes anuales, ¼ de ellas se realizan a través de aplicaciones de terceros, lo que representa un ingreso significativo.

El estilo API conforme ayuda a estandarizar a los clientes

Un problema común es cuando diferentes tipos de clientes prefieren diferentes métodos sobre cómo recuperar datos del servidor. Los equipos de ingeniería formados alrededor de áreas de características a menudo implementan la nueva característica gradualmente, una plataforma a la vez, y encuentran restricciones opuestas en cada cliente.

Lee describió cómo el equipo de FitBit tenía cuatro clientes principales: Android , iOS , Windows y Web . Un problema principal fue que Android e iOS tenían ideas muy diferentes sobre cómo debería funcionar la API. Mientras que iOS prefirió menos solicitudes de red con respuestas de API grandes, Android prefirió más solicitudes de red con respuestas de API más pequeñas.

Para normalizar estas limitaciones en un modelo de datos coherente , el equipo tuvo que resolver primero el debate entre el número de solicitudes y el tamaño de la solicitud. Trabajando en un entorno móvil con redes de datos hostiles, el equipo de FitBit no podía confiar en las conexiones de cliente ideales.

Confiando en la creciente adopción de HTTP / 2 , TLS 1.3 y redes LTE mejoradas , el equipo de FitBit resolvió que podían reducir la sobrecarga de solicitudes, realizar solicitudes simultáneas y reducir los problemas de latencia de seguridad, mientras que al mismo tiempo confiaban en más conexiones resistentes. Esto los llevaría a adoptar recursos más pequeños y muchas solicitudes HTTP ligeras.

La API JSON ayudó a crear modelos de datos consistentes

"Sin una guía clara, los modelos de datos pueden complicarse".
-Jeremiah Lee

Lee describe cómo en FitBit, sus API comenzaron a parecerse a "modelos de vista"; los puntos finales existentes se estaban sobrecargando y los datos estaban poco relacionados en lugar de tener un buen alcance. Los equipos estaban sobrecargando los puntos finales en función de las vistas de la experiencia del usuario.

A medida que la experiencia del cliente evolucionó con el tiempo, los equipos dividieron los datos de manera arbitraria . Sin autoridad o estilo a seguir, esto creó mucha inconsistencia . La desalineación entre los modelos de datos de cliente y servidor estaba creando problemas. El equipo necesitaba ponerse de acuerdo sobre cómo recuperar datos y manejarlos, y necesitaba la capacidad de verificar cambios en los datos con poca sobrecarga.

Gravitaron hacia JSON API para normalizar sus datos. Utilizando la capacidad de JSON API para definir relaciones entre datos, pudieron establecer expectativas de comunicación cliente-servidor.

La API JSON ayuda a mantenerse sincronizado

Otro problema en el caso de FitBit fue mantenerse sincronizado con el servidor. Sus dispositivos necesitan sincronizarse a menudo con el servidor, y esos datos también pueden ser modificados por aplicaciones de terceros.

Estos cambios deben reflejarse en todos los clientes de API muy rápidamente. El almacenamiento en caché HTTP  aprovechado por la  API JSON les permitió evitar la recuperación de datos obsoletos, reduciendo así la redundancia y aumentando la velocidad percibida para los usuarios finales. Según Lee, esto realmente comienza a sumarse a través de múltiples experiencias dentro de una aplicación.

Consulte también: Negociación de contenido para la longevidad de la API web

Comparación de la API JSON con GraphQL

Ya que básicamente estamos hablando de trabajar con un gráfico , ¿por qué no usar GraphQL ? Si bien puede lograr muchas de las mismas características con GraphQL, Lee ve dos beneficios principales de la adopción de la API JSON: la paginación y la capacidad de caché .

La paginación es un área que GraphQL no aborda específicamente. Alternativamente, JSON API proporciona enlaces como  nextprev para los clientes cuando los solicitan. Dado que la paginación es manejada completamente por el cliente en GraphQL, Lee considera que esto es desafortunado, ya que los clientes, sin saberlo, podrían realizar consultas de bases de datos caras y que requieren mucho tiempo.

GraphQL tampoco aprovecha las funciones de almacenamiento en caché de HTTP porque es independiente del protocolo. Dado que no existe un enfoque común sugerido, esto significa que cada API GraphQL manejará el almacenamiento en caché de manera un poco diferente.

"Personalmente creo que el almacenamiento en caché es demasiado importante para considerar el desempeño del cliente como para ser una ocurrencia tardía"
-Jeremiah Lee

Lee también señala que el uso de la API JSON significa que los desarrolladores no tienen que adoptar otra cadena de herramientas como GraphQL, pero pueden continuar usando tecnologías con las que probablemente ya estén familiarizados .

Muchos de los beneficios de GraphQL , como la eficiencia de las consultas y la reducción de las llamadas de ida y vuelta, se pueden combinar en la API JSON utilizando conjuntos de campos dispersos y documentos compuestos. Por lo tanto, la API JSON puede proporcionar el mismo tipo de funcionalidad que se encuentra en GraphQL.

Considere la API JSON para un diseño de API "pragmático"

Logotipo de la API JSON

Jeremiah Lee lo llama “pragmático” y tenemos que estar de acuerdo. Como se demostró anteriormente, existen muchas ventajas en que los clientes y servidores compartan un modelo de datos común como JSON API.

"La especificación JSONAPI.org debe ser su opción predeterminada inteligente"
- Jeremiah Lee

Si bien la API JSON no es adecuada para todas las situaciones, muchos la consideran una excelente forma predeterminada para que los clientes y servidores compartan una interfaz de datos común a través de HTTP. Con las ventajas enumeradas anteriormente, así como su adopción saludable, JSON API parece ser un fuerte competidor para el estilo API.

Le recomendamos que lea la especificación usted mismo. ¿Qué opinas de JSONAPI.org? ¿Qué especificación está utilizando para definir sus API y modelos de datos?

Recursos

  • Jeremiah Lee Slides con comentario
  • Introducción a JSON: API spec : Presentación de Marco Otte-Witte
  • Página de inicio de la API JSON
  • Especificación de la API JSON
  • Twitter de la API JSON
  • API JSON Github
  • Parche JSON : se puede utilizar para actualizaciones incrementales

Descargo de responsabilidad: Jeremiah Lee ya no trabaja en FitBit, y las ideas que compartió en la Platform Summit 2017 se proporcionaron gentilmente para dar contexto a JSONAPI.org. No se parecen a ninguna posición oficial adoptada por FitBit o Spotify.

Publicar un comentario

0 Comentarios