Глоссарий терминов

Кратко (TL;DR):

• HTTP-запросы отправляются к JSON:API ресурсам. Не путайте их с объектами ресурсов.
• JSON-объект, получаемый клиентом, называется документом.
• Документ всегда представляет собой JSON-объект и содержит основные данные под ключом data.
• Данные под этим ключом называются объектами ресурсов или объектами-идентификаторами ресурсов.
• Если вы запрашиваете вложенные связанные данные, документ становится составным документом.
• Составной документ содержит ключ included в объекте верхнего уровня.
• Ресурсы, возвращающие много объектов ресурсов, называются коллекциями ресурсов.
• Ресурсы, возвращающие один объект ресурса, называются отдельными ресурсами.
• Ресурсы, возвращающие информацию о связях между объектами ресурсов, называются ресурсами связей.
• В терминах Drupal:
  • Объекты ресурсов → Сущности
  • Объекты-идентификаторы ресурсов → Элементы полей ссылок на сущности
  • Документ → JSON-запрос/ответ

Ниже приводится краткое описание терминов и понятий, используемых для описания модуля JSON:API.

Этот глоссарий близок к спецификации JSON:API, но адаптирует определения под Drupal и расширяет некоторые нюансы спецификации, которые могут быть неочевидны для новичков или тех, кто не знаком с чтением спецификаций.

Многие из этих определений тесно связаны между собой. В диаграмме внизу страницы эти термины представлены в контексте.

Ресурс

Местоположение, по которому можно получить документ ответа JSON:API. Ресурс определяется по URL и не должен путаться с "объектом ресурса". Он не обязательно соответствует данным приложения один к одному.

В Drupal ресурс JSON:API — это не сущность. Это место, где можно получить данные по определённой концепции. Например, "коллекция объектов ресурсов типа node--article" или "значения поля field_tags конкретного узла статьи".

Документ ответа

Тело ответа в формате JSON, возвращаемое от ресурса JSON:API. Это "обёртка", через которую клиенту передаются данные или ошибки. Иногда его называют объектом верхнего уровня. Если в документе присутствует ключ included, он называется составным документом.

Составной документ

Документ ответа, содержащий элемент included. Позволяет избежать дополнительных HTTP-запросов, включая связанные объекты ресурсов вместе с основными данными. Для получения составного документа к URL добавляется параметр запроса include.

Документ ошибки

Документ ответа, содержащий элемент errors с одним или несколькими объектами ошибок. Такой документ никогда не содержит data. HTTP-статус всегда 4xx или 5xx.

Отдельный ресурс

Ресурс, содержащий один объект ресурса в элементе data документа ответа. В Drupal такой ресурс позволяет 'просматривать', 'обновлять' или 'удалять' сущность. Нельзя использовать для создания сущности.

Коллекция ресурсов

Ресурс, содержащий много объектов ресурсов в элементе data. В Drupal можно использовать для 'создания' сущностей. Нельзя использовать для 'обновления' или 'удаления' сущностей в коллекции. Поддерживает пагинацию, фильтрацию и сортировку.

Ресурс связи

Ресурс, содержащий объект связи на верхнем уровне документа ответа. Содержит один или несколько объектов-идентификаторов ресурсов, которые представляют связь между объектами ресурсов. В Drupal используется для 'просмотра' или 'редактирования' значений полей-ссылок.

Связанный ресурс

Ресурс, представляющий собой особую коллекцию ресурсов, содержащую один или более объектов ресурсов в элементе data. Эти ресурсы являются объектами, на которые ссылается поле-ссылка. Ресурс доступен только для чтения и не позволяет 'обновлять' сущности или 'редактировать' само поле-ссылку.

Элемент документа

JSON-объект, расположенный в верхнем уровне документа JSON:API. Эти объекты находятся под предопределёнными ключами, такими как jsonapi, data, included или errors.

Объект ресурса

Представление сущности в виде JSON-объекта. Не следует путать с ресурсом. Объект ресурса соответствует данным приложения один к одному.

Объект атрибутов

JSON-объект, содержащий информацию об объекте ресурса, в котором он определён. Может содержать любое допустимое JSON-значение. В Drupal это значения полей сущности, не являющиеся ссылками на другие сущности.

Объект связей

JSON-объект, содержащий ссылки от объекта ресурса к другим объектам ресурсов. Содержит множество объектов связи. В Drupal — это значения всех полей-ссылок на сущности.

Объект связи

JSON-объект, представляющий ссылки от объекта ресурса к другим объектам ресурсов. Содержит объекты-идентификаторы ресурсов, каждый из которых описывает одну связь. В Drupal — это отдельное поле-ссылка.

Объект-идентификатор ресурса

Простой JSON-объект, представляющий связь между двумя объектами ресурсов. Не является объектом ресурса. Содержит только ключи type и id, опционально — meta. Не содержит links. Используется в составных документах для сопоставления ссылок со связанными объектами.

Объект ссылок

JSON-объект, содержащий гиперссылки на другие ресурсы.

Объект ошибки

JSON-объект, представляющий ошибку, возникшую при обработке запроса. Может отражать ошибки клиента, ошибки валидации, ошибки сервера и др.

Статья с сайта Drupal Documentation.