Каталог решений - Спецификация JSON:API 1.0

От переводчика: в тексте много перекрестных ссылок, в первом проходе ими не занимался. Возможно, пропустил имена элементов, которые перевелись в слитное предложение "type" — "элементов типа". Корректировал некоторые предложения из собственного понимания обмена (с сохранением смысла). Буду рад критике и корректировкам по переводу. Считаю, что наличие спецификаций/документаций на основные технологии на русском языке будут полезны для сообщества. Спасибо Яндекс.Переводчик.

1 Состояние

На этой странице представлена последняя опубликованная версия JSON:API, которая в настоящее время является версией 1.0. Новые версии JSON:API всегда будут обратно совместимы с использованием стратегии "никогда не удалять, только добавлять". Дополнения могут быть предложены на нашем дискуссионном форуме.

Если вы обнаружите ошибку в тексте спецификации или напишете реализацию, пожалуйста, сообщите нам об этом, открыв проблему или запрос на извлечение в нашем репозитории GitHub.

2 Вступление

JSON:API — это спецификация того, как клиент должен запрашивать получение или изменение ресурсов и как сервер должен отвечать на эти запросы.

JSON:API предназначен для минимизации как количества запросов, так и объема данных, передаваемых между клиентами и серверами. Эта эффективность достигается без ущерба для удобочитаемости, гибкости или открытости.

JSON:API требует указания типа данных (application/vnd.api+json) для обмена данными.

3 Соглашения

Ключевые слова "ДОЛЖЕН", "НЕ ДОЛЖЕН", "ТРЕБУЕТСЯ", "РЕКОМЕНДУЕТСЯ", "МОЖЕТ" и "НЕОБЯЗАТЕЛЬНО" ("MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL") в этом документе должны интерпретироваться как описано в RFC 2119 [RFC2119].

4 Согласование контента

4.1 Обязанности Клиента

Клиенты ДОЛЖНЫ отправлять все данные JSON:API в документах запроса с заголовком "Content-Type:application/vnd.api+json" без каких-либо параметров типа носителя (media type).

Клиенты, которые включают тип носителя JSON:API в своем заголовке "Accept", ДОЛЖНЫ указать тип носителя там по крайней мере один раз без каких-либо параметров типа носителя.

Клиенты ДОЛЖНЫ игнорировать любые параметры для типа носителя application/vnd.api+json, полученные в заголовке типа содержимого документов ответа.

4.2 Обязанности Сервера

Серверы ДОЛЖНЫ отправлять все данные JSON:API в ответных документах с заголовком "Content-Type: application/vnd.api+json" без каких-либо параметров типа носителя.

Серверы ДОЛЖНЫ отвечать кодом состояния "415 Unsupported Media Type", если в запросе указан тип содержимого заголовка: "Content-Type: application/vnd.api+json" с любыми параметрами типа носителя.

Серверы ДОЛЖНЫ отвечать кодом состояния "406 Not Acceptable", если заголовок "Accept" запроса содержит тип носителя JSON:API, и все экземпляры этого типа носителя изменяются с помощью параметров типа носителя.

Примечание: Требования к согласованию содержимого существуют, чтобы позволить будущим версиям этой спецификации использовать параметры типа носителя для согласования расширений и управления версиями.

5 Структура документа

в этом разделе описывается структура документа JSON:API, который определяется типом носителя application/vnd.api+json. JSON: Документы API определены в Нотации объектов JavaScript (JSON) [RFC7159].

Хотя один и тот же тип носителя используется как для документов запроса, так и для документов ответа, некоторые аспекты применимы только к одному или другому. Эти различия перечислены ниже.

Если не указано иное, объекты, определенные данной спецификацией, НЕ ДОЛЖНЫ содержать никаких дополнительных элементов. Реализации клиента и сервера ДОЛЖНЫ игнорировать элементы, не распознанные этой спецификацией.

Примечание: Эти условия позволяют этой спецификации развиваться за счет изменений через дополнение.

5.1 Верхний уровень

Объект JSON ДОЛЖЕН находиться в корне каждого запроса JSON:API и ответа, содержащего данные. Этот объект определяет "верхний уровень" документа.

Документ ДОЛЖЕН содержать по крайней мере один из следующих элементов "верхнего уровня":

• data: "первичные данные" документа
• errors: массив объектов ошибок
• meta: метаобъект, содержащий нестандартную метаинформацию.

Элементы "data" и "errors" НЕ ДОЛЖНЫ сосуществовать в одном документе.

Документ МОЖЕТ содержать любого из этих элементов "верхнего уровня":

• jsonapi: объект, описывающий ссылки на реализацию сервера
• links: объект ссылок, связанный с первичными данными.
• included: массив объектов ресурсов, которые связаны с первичными данными и/или друг с другом ("включенные ресурсы").

Если документ не содержит элемента "data" верхнего уровня, элемент "included" также НЕ ДОЛЖЕН присутствовать.

Элемент "links" верхнего уровня МОЖЕТ содержать следующие элементы:

• self: ссылка, по которой был создан текущий документ ответа.
• related: ссылка на связанный ресурс, когда первичные данные представляют взаимосвязь ресурсов.
• ссылки на страницы для первичных данных (first, last, prev, next).

"Первичные данные" документа — это представление ресурса или набора ресурсов, на которые направлен запрос.

Первичные данные ДОЛЖНЫ быть либо:

• один объект ресурса, один объект идентификатора ресурса или значение null для запросов, предназначенных для отдельных ресурсов
• массив объектов ресурсов, массив объектов идентификаторов ресурсов или пустой массив ([]) для запросов, предназначенных для коллекций ресурсов

Например, следующие первичные данные являются одним ресурсным объектом:

  {
    "data": {
      "type": "articles",
      "id": "1",
      "attributes": {
        // ... атрибуты этой статьи
      },
      "relationships": {
        // ... связи в этой статье
      }
    }
  }

Cледующие первичные данные представляют собой единый объект идентификатора ресурса, который ссылается на тот же ресурс:

  {
    "data": {
      "type": "articles",
      "id": "1"
    }
  }

Логическая коллекция ресурсов ДОЛЖНА быть представлена в виде массива, даже если она содержит только один элемент или пуста.

5.2 Объекты ресурсов

"Объекты ресурсов" отображаются в документе JSON:API для представления ресурсов.

Объект ресурса ДОЛЖЕН содержать по крайней мере следующие элементы верхнего уровня:

• attributes: объект атрибутов, представляющий некоторые данные ресурса.
• relationships: объект отношений, описывающий отношения между ресурсом и другими ресурсами JSON:API.
• links: объект ссылок, содержащий ссылки, связанные с ресурсом.
• meta: метаобъект, содержащий нестандартную метаинформацию о ресурсе, которая не может быть представлена в виде атрибута или отношения.

Вот как статья (т.е. ресурс типа "статьи") может отображаться в документе:

  // ...
  {
    "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" }
      }
    }
  }
  // ...

5.2.1 Идентификация

Каждый объект ресурса ДОЛЖЕН содержать элемент идентификатора (id) и элемент типа (type). Значения элементов идентификатора и типа ДОЛЖНЫ быть строками.

В рамках данного API тип и пара идентификаторов каждого объекта ресурса ДОЛЖНЫ идентифицировать один уникальный ресурс. (Набор URI, управляемых сервером или несколькими серверами, действующими как один, составляют API.)

Элемент типа используется для описания объектов ресурсов, которые имеют общие атрибуты и связи.

Значения элементов типа ДОЛЖНЫ соответствовать тем же ограничениям, что и имена элементов.

Примечание: Эта спецификация не зависит от правил словообразования, поэтому значение типа может быть как множественным, так и единственным числом. Однако одно и то же значение должно последовательно использоваться на протяжении всей реализации.

5.2.2 Поля

Атрибуты объекта ресурса и его взаимосвязи в совокупности называются его “полями”.

Поля для объекта ресурса ДОЛЖНЫ иметь общее пространство имен друг с другом, а также type и id. Другими словами, ресурс не может иметь атрибут и связь с одним и тем же именем, а также не может иметь атрибут или связь с именем type или id.

5.2.3 Атрибуты

Значение ключа атрибутов ДОЛЖНО быть объектом (“объект атрибутов”). Элементы объекта атрибутов (“атрибуты”) представляют информацию об объекте ресурса, в котором он определен.

Атрибуты могут содержать любое допустимое значение JSON.

В качестве значений атрибутов допускаются сложные структуры данных, включающие объекты и массивы JSON. Однако любой объект, который составляет или содержится в атрибуте, НЕ ДОЛЖЕН содержать элемент отношений ("relationships") или связей ("links"), поскольку эти элементы зарезервированы данной спецификацией для использования в будущем.

Хотя внешние ключи has-one (например, author_id) часто хранятся внутри вместе с другой информацией, которая должна быть представлена в объекте ресурса, эти ключи НЕ ДОЛЖНЫ отображаться в качестве атрибутов.

Примечание. Дополнительные ограничения для этого контейнера см. в разделах "Поля" и "Имена участников".

5.2.4 Отношения (Relationships)

Значение ключа отношений ДОЛЖНО быть объектом ("Объект отношений"). Члены объекта отношений ("relationships") представляют ссылки из объекта ресурса, в котором он определен, на другие объекты ресурсов.

Отношения могут быть как с одним, так и со многими.

"Объект отношений" ДОЛЖЕН содержать по крайней мере одно из следующих:

• links: объект ссылок, содержащий по крайней мере одно из следующих:
  • self: ссылка для самих отношений ("ссылка на отношения"). Эта ссылка позволяет клиенту напрямую манипулировать отношениями. Например, удаление автора через URL-адрес связи статьи приведет к отключению пользователя от статьи без удаления самого ресурса "Люди". При успешном извлечении эта ссылка возвращает связь для связанных ресурсов в качестве основных данных. (См. Раздел Выбор Отношений.)
  • related: связанная ссылка на ресурс
• data: связь ресурсов
• meta: метаобъект, содержащий нестандартную метаинформацию об отношениях.

Объект отношения, представляющий отношение "ко многим", также может содержать ссылки пагинации в элементе "links", как описано ниже. Любые ссылки на пагинации на страницы в объекте взаимосвязи ДОЛЖНЫ содержать данные о взаимосвязи, а не связанные ресурсы.

Примечание. Дополнительные ограничения для этого контейнера см. в разделе Поля и имена участников.

5.2.5 Ссылки на Связанные Ресурсы

"Ссылка на связанный ресурс" предоставляет доступ к объектам ресурсов, связанным в отношениях. При извлечении связанные объекты ресурсов возвращаются в качестве первичных данных ответа.

Например, связь комментариев статьи может указывать ссылку, которая возвращает коллекцию объектов ресурсов комментариев при получении с помощью запроса GET.

Если ссылка на связанный ресурс присутствует, ОНА ДОЛЖНА ссылаться на действительный URL-адрес, даже если связь в настоящее время не связана ни с какими целевыми ресурсами. Кроме того, ссылка на связанный ресурс НЕ ДОЛЖНА изменяться из-за изменения содержимого ее взаимосвязи.

5.2.6 Связь с ресурсами

Связь ресурсов в составном документе позволяет клиенту связать вместе все включенные объекты ресурсов без необходимости ПОЛУЧАТЬ какие-либо URL-адреса по ссылкам.

Связь ресурсов ДОЛЖНА быть представлена одним из следующих способов:

• null для пустого отношения "к одному".
• пустой массив ([]) для пустых отношений "ко многим".
• единый объект идентификатора ресурса для непустых отношений "один к одному".
• массив объектов идентификаторов ресурсов для непустых отношений "ко многим".

Примечание: Спецификация не придает значения порядку объектов идентификаторов ресурсов в массивах связей отношений "ко многим", хотя реализации могут это делать. Массивы объектов идентификаторов ресурсов могут представлять упорядоченные или неупорядоченные отношения, и оба типа могут быть смешаны в одном объекте ответа.

Например, следующая статья связана с автором:

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

Cвязь с автором включает ссылку для самой связи (которая позволяет клиенту напрямую изменять связанного автора), ссылку на связанный ресурс для извлечения объектов ресурсов и информацию о связи.

5.2.7 Ссылки на ресурсы

Необязательный элемент "links" в каждом объекте ресурса содержит ссылки, связанные с ресурсом.

Если этот объект ссылок присутствует, он МОЖЕТ содержать "self" ссылку, которая идентифицирует ресурс, представленный объектом ресурса.

  // ...
  {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "Rails is Omakase"
    },
    "links": {
      "self": "http://example.com/articles/1"
    }
  }
  // ...

Сервер ДОЛЖЕН ответить на запрос GET по указанному URL-адресу ответом, включающим ресурс в качестве основных данных.

5.3 Объекты идентификаторов ресурсов

"Объект идентификатора ресурса" — это объект, идентифицирующий отдельный ресурс.

"Объект идентификатора ресурса" ДОЛЖЕН содержать элементы "type" и "id".

"Объект идентификатора ресурса" МОЖЕТ также включать элемент "meta", значением которого является метаобъект, содержащий нестандартную метаинформацию.

5.4 Составные Документы

Чтобы уменьшить количество HTTP-запросов, серверы МОГУТ разрешать ответы, которые включают связанные ресурсы вместе с запрошенными основными ресурсами. Такие ответы называются “составными документами”.

В составном документе все включенные ресурсы ДОЛЖНЫ быть представлены в виде массива объектов ресурсов в включенном элементе верхнего уровня.

Составные документы требуют “полной увязки”, что означает, что каждый включенный ресурс ДОЛЖЕН быть идентифицирован по крайней мере одним объектом идентификатора ресурса в одном документе. Эти объекты идентификаторов ресурсов могут быть либо первичными данными, либо представлять связь ресурсов, содержащуюся в первичных или включенных ресурсах.

Единственное исключение из требования полной привязки — это когда поля связей, которые в противном случае содержали бы данные о связях, исключаются с помощью разреженных наборов полей.

Примечание: Полная связь гарантирует, что включенные ресурсы связаны либо с первичными данными (которые могут быть объектами ресурсов или объектами идентификаторов ресурсов), либо друг с другом.