Glosario de términos

Resumen (TL;DR):

• Las peticiones HTTP se hacen a recursos de JSON:API. No los confundas con objetos recurso.
• El objeto JSON que recibe el cliente se llama documento.
• Un documento siempre es un objeto JSON y contiene los datos principales bajo la clave data.
• Los datos bajo esa clave se llaman objetos recurso o objetos identificadores de recurso.
• Cuando solicitas que los datos relacionados se incluyan en el documento, se convierte en un documento compuesto.
• Un documento compuesto es aquel que tiene una clave included en el objeto de nivel superior.
• Los recursos que devuelven muchos objetos recurso se denominan recursos colección.
• Los recursos que devuelven un solo objeto recurso se llaman recursos individuales.
• Los recursos que devuelven información sobre relaciones entre objetos recurso se llaman recursos de relación.
• En términos de Drupal:
  • Resource Objects (objetos recurso) → Entidades
  • Resource Identifier Objects (objetos identificadores de recurso) → Elementos de campo de referencia de entidad
  • Document (documento) → Carga JSON de la petición/respuesta

A continuación se proporciona una breve descripción de los términos y conceptos utilizados al describir el módulo JSON:API.

Este glosario se basa en la especificación JSON:API, pero trata de definir los términos tal como se aplican en Drupal y amplía detalles sutiles que pueden no ser obvios para quienes no están familiarizados con la especificación o cómo leer una especificación.

Muchas de estas definiciones están relacionadas entre sí. Hay un diagrama al final de la página que muestra estos términos en contexto.

Recurso (Resource)

Una ubicación donde se puede obtener un documento de respuesta de JSON:API. Un recurso se localiza mediante su URL (localizador universal de recursos). No debe confundirse con un "objeto recurso". Un recurso no tiene correspondencia uno a uno con los datos de la aplicación.

En Drupal, un recurso de JSON:API no es sinónimo de entidad. Un recurso es un lugar donde puedes obtener los datos para un concepto. Por ejemplo, ese concepto puede ser “una colección de objetos recurso del tipo node--article” o “una representación del campo de referencia field_tags de un nodo artículo en particular”.

Documento de respuesta (Response Document)

El cuerpo codificado en JSON que retorna un recurso de JSON:API. Es el “envoltorio” donde se comunican los datos o errores al cliente HTTP. A veces se le llama el objeto de nivel superior. Cuando un documento tiene un miembro included, se le denomina documento compuesto.

Documento compuesto (Compound Document)

Un documento de respuesta que contiene una clave included. Un documento compuesto se utiliza para eliminar peticiones HTTP adicionales al incrustar objetos recurso relacionados junto con los datos principales de la respuesta. Se solicita añadiendo el parámetro include a la URL de la petición.

Documento de error (Error Document)

Un documento de respuesta que contiene una clave errors con uno o más objetos de error. Nunca contendrá una clave data. El código HTTP de respuesta de un documento de error será siempre de la serie 4xx o 5xx.

Recurso individual (Individual Resource)

Un recurso que contiene un solo objeto recurso bajo la clave data del documento de respuesta. Con autorización suficiente, este recurso es legible y modificable. En Drupal, este recurso se puede usar para ‘ver’, ‘actualizar’ o ‘eliminar’ una entidad individual. No se puede usar para ‘crear’ una entidad.

Recurso colección (Collection Resource)

Un recurso que contiene muchos objetos recurso bajo la clave data del documento de respuesta. Con autorización suficiente, este recurso es legible y escribible. Estos recursos pueden ser paginados, filtrados y ordenados. En Drupal, este recurso se puede usar para ‘crear’ una nueva entidad. No se puede usar para ‘actualizar’ o ‘eliminar’ entidades en la colección.

Recurso de relación (Relationship Resource)

Un recurso que contiene un objeto de relación como objeto de nivel superior en el documento de respuesta. Contiene uno o más objetos identificadores de recurso que representan referencias desde un objeto recurso a otro. Con autorización suficiente, este recurso es legible y modificable. En Drupal, este recurso puede usarse para ‘ver’ o ‘editar’ los elementos de un campo de referencia de entidad.

Recurso relacionado (Related Resource)

Un recurso que es una colección especial que contiene uno o más objetos recurso como miembro data del documento de respuesta. Los objetos recurso en esta colección son los sujetos de una relación en un objeto recurso referenciador. Este recurso es solo de lectura. En Drupal, este recurso se usa para ‘ver’ entidades referenciadas por un campo de referencia de entidad, pero no para ‘actualizar’ esas entidades ni ‘editar’ el campo de referencia que las enlaza.

Miembro de documento (Document member)

Un objeto JSON que forma parte del documento JSON:API de nivel superior. Estos objetos siempre se ubican bajo claves definidas por la especificación (por ejemplo, jsonapi, data, included o errors).

Objeto recurso (Resource Object)

Una representación de una entidad como un objeto JSON. No debe confundirse con un "recurso". Este sí tiene correspondencia uno a uno con los datos de la aplicación.

Objeto atributos (Attributes Object)

Un objeto JSON que representa información sobre el objeto recurso en el que se define. Los atributos pueden contener cualquier valor JSON válido. En Drupal, este objeto representa todos los valores de campos de entidad que no son referencias a otras entidades.

Objeto relaciones (Relationships Object, plural)

Un objeto JSON que contiene referencias desde el objeto recurso donde se define hacia otros objetos recurso. Contiene múltiples miembros, que son objetos de relación (singular). En Drupal, este objeto representa todos los valores de campos de referencia de entidad.

Objeto de relación (Relationship Object, singular)

Un objeto JSON que representa las referencias desde el objeto recurso donde se define hacia otros objetos recurso. Contiene objetos identificadores de recurso, cada uno representando una relación individual hacia otro objeto recurso. En Drupal, este objeto representa un único campo de referencia de entidad.

Objeto identificador de recurso (Resource Identifier Object)

Un objeto JSON muy simple que representa una relación de un objeto recurso a otro. No debe confundirse con un "objeto recurso". Contiene solo una clave type y una clave id, y una clave opcional meta para información adicional sobre esa relación. Importante: no contiene un miembro links.

Proporciona “enlace de recursos” que, en un documento compuesto, permite al cliente HTTP correlacionar objetos de relación con los objetos recurso referenciados que aparecen en el miembro included del documento compuesto.

Objeto enlaces (Links Object)

Un objeto JSON que contiene hipervínculos a otros recursos.

Objeto de error (Error Object)

Un objeto JSON que representa un error ocurrido durante el procesamiento de una solicitud. Puede representar errores de cliente, errores de validación o errores de servidor, entre otros.

Artículo de la Documentación de Drupal.