Спецификация 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-запросов, серверы МОГУТ разрешать ответы, которые включают связанные ресурсы вместе с запрошенными основными ресурсами. Такие ответы называются “составными документами”.

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

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

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

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

{
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!"
    },
    "links": {
      "self": "http://example.com/articles/1"
    },
    "relationships": {
      "author": {
        "links": {
          "self": "http://example.com/articles/1/relationships/author",
          "related": "http://example.com/articles/1/author"
        },
        "data": { "type": "people", "id": "9" }
      },
      "comments": {
        "links": {
          "self": "http://example.com/articles/1/relationships/comments",
          "related": "http://example.com/articles/1/comments"
        },
        "data": [
          { "type": "comments", "id": "5" },
          { "type": "comments", "id": "12" }
        ]
      }
    }
  }],
  "included": [{
    "type": "people",
    "id": "9",
    "attributes": {
      "first-name": "Dan",
      "last-name": "Gebhardt",
      "twitter": "dgeb"
    },
    "links": {
      "self": "http://example.com/people/9"
    }
  }, {
    "type": "comments",
    "id": "5",
    "attributes": {
      "body": "First!"
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "2" }
      }
    },
    "links": {
      "self": "http://example.com/comments/5"
    }
  }, {
    "type": "comments",
    "id": "12",
    "attributes": {
      "body": "I like XML better"
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "9" }
      }
    },
    "links": {
      "self": "http://example.com/comments/12"
    }
  }]
}

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

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

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

5.5 Метаинформация

Метаинформация
Если указано, элемент "meta" может использоваться для включения нестандартной метаинформации. Значением каждого элемента "meta" ДОЛЖЕН быть объект ("мета-объект").

В объектах "meta" МОГУТ быть указаны любые объекты.

Например:

{
  "meta": {
    "copyright": "Copyright 2015 Example Corp.",
    "authors": [
      "Yehuda Katz",
      "Steve Klabnik",
      "Dan Gebhardt",
      "Tyler Kellen"
    ]
  },
  "data": {
    // ...
  }
}

5.6 Ссылки

Если указано, элемент "links" может использоваться для представления ссылок. Значение каждого элемента "links" ДОЛЖНО быть объектом ("объект ссылок").

Каждый элемент объекта links является "ссылкой". Ссылка ДОЛЖНА быть представлена в виде либо:

• строка, содержащая URL-адрес ссылки.
• объект ("объект связи"), который может содержать следующие элементы:
  • href: строка, содержащая URL-адрес ссылки.
  • meta: метаобъект, содержащий нестандартную метаинформацию о ссылке.

Следующая самостоятельная ссылка - это просто URL-адрес:

"links": {
  "self": "http://example.com/posts"
}

Следующая связанная ссылка содержит URL-адрес, а также метаданные о соответствующей коллекции ресурсов:

"links": {
  "related": {
    "href": "http://example.com/articles/1/comments",
    "meta": {
      "count": 10
    }
  }
}

Примечание: В будущем для объектов ссылок и объектов ссылок могут быть указаны дополнительные элементы. Также возможно, что допустимые значения дополнительных элементов будут расширены (например, "links" на коллекцию может поддерживать массив значений, в то время как "self" этого не делает).

5.7 Объект JSON:API

Документ JSON:API МОЖЕТ содержать информацию о его реализации в рамках элемента jsonapi верхнего уровня. Если присутствует, значение элемента jsonapi ДОЛЖНО быть объектом ("объект jsonapi"). Объект jsonapi МОЖЕТ содержать элемент "version", значение которого представляет собой строку, указывающую самую высокую поддерживаемую версию API JSON. Этот объект также МОЖЕТ содержать элемент "meta", значением которого является метаобъект, содержащий нестандартную метаинформацию.

{
  "jsonapi": {
    "version": "1.0"
  }
}

Если элемент "version" отсутствует, клиенты должны предположить, что сервер реализует по крайней мере версию 1.0 спецификации.

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

5.8 Имена элементов

Все имена участников, используемые в документе JSON:API, ДОЛЖНЫ учитываться клиентами и серверами с учетом регистра, и они ДОЛЖНЫ соответствовать всем следующим условиям:

• Имена участников ДОЛЖНЫ содержать по крайней мере один символ.
• Имена участников ДОЛЖНЫ содержать только разрешенные символы, перечисленные ниже.
• Имена участников ДОЛЖНЫ начинаться и заканчиваться "глобально разрешенным символом", как определено ниже.

Чтобы упростить сопоставление имен участников с URL-адресами, рекомендуется, чтобы в именах участников использовались только не зарезервированные, безопасные для URL-адресов символы, указанные в RFC 3986.

5.8.1 Разрешенные Символы

Следующие "глобально разрешенные символы" МОГУТ использоваться в любом месте имени элемента:

• U+0061 to U+007A, "a-z"
• U+0041 to U+005A, "A-Z"
• U+0030 to U+0039, "0-9"
• U+0080 и выше (символы Юникода, отличные от ASCII; не рекомендуется, не безопасны для URL-адресов)

Кроме того, в именах элементов допускаются следующие символы, за исключением первого или последнего символа:

• U+002D HYPHEN-MINUS, "-"
• U+005F LOW LINE, "_"
• U+0020 SPACE, " " (не рекомендуется, не безопасны для URL-адресов)

5.8.2 Зарезервированные Символы

В именах элементов НЕ ДОЛЖНЫ использоваться следующие символы:

6 Получение Данных (Fetching Data)

Данные, включая ресурсы и взаимосвязи, могут быть извлечены путем отправки запроса GET в конечную точку.

Ответы могут быть дополнительно уточнены с помощью дополнительных функций, описанных ниже.

6.1 Получение Ресурсов

Сервер ДОЛЖЕН поддерживать получение данных ресурсов для каждого URL-адреса, предоставленного как:

• через элемент "self" как часть объекта связей верхнего уровня
• через элемент "self" как часть объекта связей на уровне ресурсов
• через элемент "related" как часть объекта связей на уровне отношений

Например, следующий запрос извлекает коллекцию статей:

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

Следующий запрос извлекает статью:

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

И следующий запрос возвращает автора статьи:

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

6.1.1 Ответы

6.1.1.1 200 OK

Сервер ДОЛЖЕН ответить на успешный запрос на извлечение отдельного ресурса или коллекции ресурсов с ответом 200 OK.

Сервер ДОЛЖЕН ответить на успешный запрос на получение коллекции ресурсов с массивом объектов ресурсов или пустым массивом ([]) в качестве первичных данных документа ответа.

Например, запрос GET на коллекцию статей может возвращать:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "http://example.com/articles"
  },
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!"
    }
  }, {
    "type": "articles",
    "id": "2",
    "attributes": {
      "title": "Rails is Omakase"
    }
  }]
}

Аналогичный ответ, представляющий пустую коллекцию, будет:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "http://example.com/articles"
  },
  "data": []
}

Сервер ДОЛЖЕН ответить на успешный запрос на извлечение отдельного ресурса с объектом ресурса или null, предоставленным в качестве первичных данных документа ответа.

значение null является подходящим ответом только в том случае, если запрошенный URL-адрес может соответствовать одному ресурсу, но в настоящее время нет на него ссылки.

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

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

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "http://example.com/articles/1"
  },
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!"
    },
    "relationships": {
      "author": {
        "links": {
          "related": "http://example.com/articles/1/author"
        }
      }
    }
  }
}

Если автор вышеупомянутой статьи отсутствует, то запрос GET на соответствующий ресурс вернет:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "http://example.com/articles/1/author"
  },
  "data": null
}

6.1.1.2 404 Not Found

Сервер ДОЛЖЕН ответить с "404 Not Found" при обработке запроса на извлечение одного несуществующего ресурса, за исключением случаев, когда запрос требует ответа "200 OK" с null в качестве первичных данных (как описано выше).

6.1.1.3 Прочие Ответы

Сервер МОЖЕТ отвечать другими кодами состояния HTTP.

Сервер МОЖЕТ включать сведения об ошибках с ответами на ошибки.

Сервер ДОЛЖЕН подготовить ответы, а клиент ДОЛЖЕН интерпретировать ответы в соответствии с семантикой HTTP.

6.2 Получение Связей

Cервер ДОЛЖЕН поддерживать извлечение данных отношений для каждого URL-адреса отношений, предоставленного в качестве "self" ссылки как часть отношений объекта "links".

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

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

И следующий запрос извлекает данные об авторе статьи:

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

6.2.1 Ответы

6.2.1.1 200 OK

Сервер ДОЛЖЕН ответить на успешный запрос для получения связи с ответом 200 OK.

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

Объект ссылок верхнего уровня МОЖЕТ содержать "self" и "related" ссылки, как описано выше для объектов отношений.

Например, запрос GET на URL-адрес из ссылки связи "к одному" может возвращать:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "/articles/1/relationships/author",
    "related": "/articles/1/author"
  },
  "data": {
    "type": "people",
    "id": "12"
  }
}

Если приведенная выше связь пуста, то запрос GET на тот же URL-адрес вернет:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "/articles/1/relationships/author",
    "related": "/articles/1/author"
  },
  "data": null
}

Запрос GET на URL-адрес из ссылки отношений "ко многим" может возвращать:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "/articles/1/relationships/tags",
    "related": "/articles/1/tags"
  },
  "data": [
    { "type": "tags", "id": "2" },
    { "type": "tags", "id": "3" }
  ]
}

Если приведенная выше связь пуста, то запрос GET на тот же URL-адрес вернет:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "/articles/1/relationships/tags",
    "related": "/articles/1/tags"
  },
  "data": []
}

6.2.1.2 404 Not Found

Сервер ДОЛЖЕН возвращать "404 Not Found" при обработке запроса на получение URL-адреса ссылки на связь, который не существует.

Примечание: Это может произойти, когда родительский ресурс связи не существует. Например, если /articles/1 не существует, запрос в /articles/1/отношения/теги возвращает "404 Not Found".

Если URL-адрес ссылки на связь существует, но связь пуста, необходимо вернуть 200 OK, как описано выше.

6.2.1.3 Прочие Ответы

Сервер МОЖЕТ отвечать другими кодами состояния HTTP.

Сервер МОЖЕТ включать сведения об ошибках с ответами на ошибки.

Сервер ДОЛЖЕН подготовить ответы, а клиент ДОЛЖЕН интерпретировать ответы в соответствии с семантикой HTTP.

6.3 Включение соответствующих ресурсов

Конечная точка МОЖЕТ по умолчанию возвращает ресурсы, связанные с первичными данными.

Конечная точка МОЖЕТ также поддерживать параметр запроса "include", позволяющий клиенту настраивать, какие связанные ресурсы должны быть возвращены.

Если конечная точка не поддерживает параметр "include", она ДОЛЖНА отвечать "400 Bad Request" на любые запросы, которые его включают.

Если конечная точка поддерживает параметр "include" и его указывает клиент, сервер НЕ ДОЛЖЕН включать объекты ресурсов, не запрошенные в разделе "included" составного документа.

Значение параметра include ДОЛЖНО быть разделенным запятыми (U+002C COMMA, ",") списком путей связи. Путь к отношениям представляет собой разделенный точками (U+002E FULL-STOP, ".") список имен отношений.

Если сервер не может определить путь связи или не поддерживает включение ресурсов из пути, он ДОЛЖЕН ответить "400 Bad Request".

Примечание: Например, путь к связи может быть comments.author, где comments - это связь, указанная в объекте ресурса "Статьи", а author - это связь, указанная в объекте ресурса "Комментарии".

Например, комментарии могут быть запрошены вместе со статьей:

GET /articles/1?include=comments HTTP/1.1
Accept: application/vnd.api+json

Чтобы запросить ресурсы, связанные с другими ресурсами, можно указать путь, разделенный точками, для каждого имени связи:

GET /articles/1?include=comments.author HTTP/1.1
Accept: application/vnd.api+json

Примечание: Поскольку для составных документов требуется полная связь (за исключением случаев, когда связь отношений исключается разреженными наборами полей), промежуточные ресурсы в многосоставном пути должны быть возвращены вместе с конечными узлами. Например, ответ на запрос "comments.author" должен включать "comments", а также "author" каждого из этих "comments".

Примечание: Сервер может выбрать предоставление глубоко вложенной связи, такой как comments.author, в качестве прямой связи с псевдонимом, таким как comment-authors. Это позволило бы клиенту запрашивать /articles/1?include=comment-authors вместо /articles/1?include=comments.author. Абстрагируя вложенные отношения с помощью псевдонима, сервер все равно может обеспечить полную связь в составных документах без включения потенциально нежелательных промежуточных ресурсов.

В списке, разделенном запятыми, можно запросить несколько связанных ресурсов:

GET /articles/1?include=author,comments.author HTTP/1.1
Accept: application/vnd.api+json

Кроме того, связанные ресурсы могут быть запрошены из конечной точки связи:

GET /articles/1/relationships/comments?include=comments.author HTTP/1.1
Accept: application/vnd.api+json

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

Примечание: Этот раздел применяется к любой конечной точке, которая отвечает первичными данными, независимо от типа запроса. Например, сервер может поддерживать включение связанных ресурсов вместе с запросом POST для создания ресурса или связи.

6.4 Разреженные наборы полей

Клиент МОЖЕТ запросить, чтобы конечная точка возвращала только определенные поля в ответе для каждого типа, включив параметр fields[TYPE].

Значение параметра fields ДОЛЖНО быть разделенным запятыми (U+002C COMMA, ",") списком, который ссылается на имена возвращаемых полей. Пустое значение указывает на то, что поля возвращать не следует.

Если клиент запрашивает ограниченный набор полей для данного типа ресурсов, конечная точка НЕ ДОЛЖНА включать дополнительные поля в объекты ресурсов этого типа в своем ответе.

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

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

Примечание: Приведенный выше пример URI показывает некодированные символы "[" и "]" просто для удобства чтения. На практике эти символы должны быть закодированы в через символ "%" в соответствии с требованиями RFC 3986.

Примечание: Этот раздел применяется к любой конечной точке, которая отвечает ресурсами в качестве основных или включенных данных, независимо от типа запроса. Например, сервер может поддерживать разреженные наборы полей вместе с запросом POST для создания ресурса.

6.5 Сортировка

Сервер МОЖЕТ поддерживать запросы на сортировку коллекций ресурсов в соответствии с одним или несколькими критериями ("поля сортировки").

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

Примечание: Рекомендуется использовать поля сортировки, разделенные точками (U+002E FULL-STOP, "."), для запроса сортировки на основе атрибутов отношений. Например, поле сортировки author.name может использоваться для запроса сортировки первичных данных на основе атрибута имени отношения автора.

Конечная точка МОЖЕТ поддерживать запросы на сортировку первичных данных с помощью параметра запроса "sort". Значение "sort" ДОЛЖНО представлять поля сортировки.

GET /people?sort=age HTTP/1.1
Accept: application/vnd.api+json

Конечная точка МОЖЕТ поддерживать несколько полей сортировки, разрешая поля сортировки, разделенные запятыми (U+002C COMMA, “,”). Поля сортировки ДОЛЖНЫ применяться в указанном порядке.

GET /people?sort=age,name HTTP/1.1
Accept: application/vnd.api+json

Порядок сортировки для каждого поля сортировки ДОЛЖЕН быть возрастающим, если только он не имеет префикса минус (U+002D HYPHEN-MINUS, "-"), в этом случае он ДОЛЖЕН быть убывающим.

GET /articles?sort=-created,title HTTP/1.1
Accept: application/vnd.api+json

В приведенном выше примере сначала должны быть возвращены самые новые статьи. Все статьи, созданные в ту же дату, будут затем отсортированы по названию в алфавитном порядке по возрастанию.

Если сервер не поддерживает сортировку, как указано в параметре запроса "sort", он ДОЛЖЕН вернуть "400 Bad Request".

Если сортировка поддерживается сервером и запрашивается клиентом с помощью параметра запроса sort, сервер ДОЛЖЕН возвращать элементы массива данных верхнего уровня ответа, упорядоченные в соответствии с указанными критериями. Сервер МОЖЕТ применить правила сортировки по умолчанию к данным верхнего уровня, если параметр запроса sort не указан.

Примечание: Этот раздел применяется к любой конечной точке, которая отвечает сбором ресурсов в качестве первичных данных, независимо от типа запроса.

6.6 Пагинация

Сервер МОЖЕТ ограничить количество ресурсов, возвращаемых в ответе, подмножеством ("страницей") всего доступного набора.

Сервер МОЖЕТ предоставлять ссылки для просмотра разбитого на страницы набора данных ("ссылки разбиения на страницы").

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

Для ссылок на страницы НЕОБХОДИМО использовать следующие ключи:

• first: первая страница данных
• last: последняя страница данных
• prev: предыдущая страница данных
• next: следующая страница данных

Ключи ДОЛЖНЫ быть либо опущены, либо иметь значение null, чтобы указать, что определенная ссылка недоступна.

Концепции сортировки, выраженные в именовании ссылок на страницы, ДОЛЖНЫ соответствовать правилам сортировки JSON:API.

Параметр запроса "page" зарезервирован для разбиения на страницы. Серверы и клиенты ДОЛЖНЫ использовать этот ключ для операций разбиения на страницы.

Примечание: JSON:API не зависит от стратегии разбиения на страницы, используемой сервером. Эффективные стратегии разбиения на страницы включают (но не ограничиваются ими): на основе страниц, на основе смещения и на основе курсора. Параметр запроса страницы может быть использован в качестве основы для любой из этих стратегий. Например, стратегия на основе страницы может использовать параметры запроса, такие как страница[номер] и страница[размер], стратегия на основе смещения может использовать страницу[смещение] и страницу[ограничение], в то время как стратегия на основе курсора может использовать страницу[курсор].

Примечание: В приведенном выше примере параметров запроса используются некодированные символы "[" и "]" просто для удобства чтения. На практике эти символы должны быть закодированы в процентах в соответствии с требованиями RFC 3986.

Примечание: Этот раздел применяется к любой конечной точке, которая отвечает сбором ресурсов в качестве первичных данных, независимо от типа запроса.

6.7 Фильтрация

Параметр запроса "filter" зарезервирован для фильтрации данных. Серверы и клиенты ДОЛЖНЫ использовать этот ключ для операций фильтрации.

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

7 Создание, Обновление и Удаление ресурсов

Сервер МОЖЕТ разрешать создавать ресурсы определенного типа. Это также может позволить изменять или удалять существующие ресурсы.

Запрос ДОЛЖЕН быть полностью успешным или неудачным (в одной “транзакции”). Частичные обновления не допускаются.

Примечание: Элемент "type" требуется в каждом объекте ресурса во всех запросах и ответах в JSON:API. В некоторых случаях, например при отправке в конечную точку, представляющую разнородные данные, тип не может быть выведен из конечной точки. Однако сбор и выбор того, когда это необходимо, привел бы к путанице; было бы трудно понять, когда это было необходимо, а когда нет. Поэтому для повышения согласованности и минимизации путаницы всегда требуется "type".

7.1 Создание Ресурсов

Ресурс можно создать, отправив запрос POST на URL-адрес, представляющий коллекцию ресурсов. Запрос ДОЛЖЕН содержать один объект ресурса в качестве первичных данных. Объект ресурса ДОЛЖЕН содержать по крайней мере элемент "type".

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

POST /photos HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "photos",
    "attributes": {
      "title": "Ember Hamster",
      "src": "http://example.com/images/productivity.png"
    },
    "relationships": {
      "photographer": {
        "data": { "type": "people", "id": "9" }
      }
    }
  }
}

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

7.1.1 Идентификаторы, сгенерированные клиентом

Сервер МОЖЕТ принять сгенерированный клиентом идентификатор вместе с запросом на создание ресурса. Идентификатор ДОЛЖЕН быть указан с помощью параметра "id", значение которого ДОЛЖНО быть универсальным уникальным идентификатором. Клиент ДОЛЖЕН использовать правильно сгенерированный и отформатированный UUID, как описано в RFC 4122 [RFC 4122].

ПРИМЕЧАНИЕ: В некоторых случаях использования, таких как импорт данных из другого источника, может быть возможно использовать что-то другое, кроме идентификатора UUID, который по-прежнему гарантированно будет уникальным в глобальном масштабе. Не используйте ничего, кроме UUID, если вы не уверены на 100 %, что используемая вами стратегия действительно генерирует глобальные уникальные идентификаторы.

Например:

POST /photos HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "photos",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "title": "Ember Hamster",
      "src": "http://example.com/images/productivity.png"
    }
  }
}

Сервер ДОЛЖЕН вернуть "403 Forbidden" в ответ на неподдерживаемый запрос на создание ресурса с идентификатором, сгенерированным клиентом.

7.1.2 Ответы

7.1.2.1 201 Created

Если запрос POST не включал идентификатор, сгенерированный клиентом, и запрошенный ресурс был успешно создан, сервер ДОЛЖЕН вернуть код состояния "201 Created".

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

Ответ ТАКЖЕ ДОЛЖЕН включать документ, содержащий созданный основной ресурс.

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

7.1.2.2 202 Accepted

Если запрос на создание ресурса был принят для обработки, но обработка не была завершена к моменту ответа сервера, сервер ДОЛЖЕН вернуть код состояния "202 Accepted".

7.1.2.3 204 No Content

Если запрос POST включал идентификатор сгенерированный клиентом, и запрошенный ресурс был успешно создан, сервер ДОЛЖЕН вернуть либо код состояния "201 Created" и документ ответа (как описано выше), либо кода состояния "204 No Content" без документа ответа.

Примечание: Если получен ответ "204", клиент должен считать, что объект ресурса, отправленный в запросе, должен быть принят сервером, как если бы сервер вернул его обратно в ответе "201".

7.1.2.4 403 Forbidden

Сервер МОЖЕТ вернуть 403 Forbidden в ответ на неподдерживаемый запрос на создание ресурса.

7.1.2.5 404 Not Found

Сервер ДОЛЖЕН возвращать 404 Not Found при обработке запроса, который ссылается на связанный ресурс, который не существует.

7.1.2.6 409 Conflict

Сервер ДОЛЖЕН возвращать "409 Conflict" при обработке запроса POST для создания ресурса с уже существующим идентификатором, созданным клиентом.

Сервер ДОЛЖЕН возвращать "409 Conflict" при обработке запроса POST, в котором тип объекта ресурса не входит в число типов, составляющих коллекцию, представленную конечной точкой.

Сервер ДОЛЖЕН содержать подробные сведения об ошибке и предоставлять достаточно информации, чтобы распознать источник конфликта.

7.1.2.7 Прочие Ответы

Сервер МОЖЕТ отвечать другими кодами состояния HTTP.

Сервер МОЖЕТ включать сведения об ошибках с ответами на ошибки.

Сервер ДОЛЖЕН подготовить ответы, а клиент ДОЛЖЕН интерпретировать ответы в соответствии с семантикой HTTP.

7.2 Обновление Ресурсов

Ресурс можно обновить, отправив запрос на PATCH по URL-адресу, представляющему ресурс.

URL-адрес ресурса можно получить в "self" ссылке объекта ресурса. В качестве альтернативы, когда запрос GET возвращает один объект ресурса в качестве первичных данных, тот же URL-адрес запроса может использоваться для обновлений.

Запрос PATCH ДОЛЖЕН включать в себя один объект ресурса в качестве первичных данных. Объект ресурса ДОЛЖЕН содержать элементы "type" и "id".

Например:

PATCH /articles/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "To TDD or Not"
    }
  }
}

7.2.1 Обновление атрибутов ресурса

Любой или все атрибуты ресурса МОГУТ быть включены в объект ресурса, включенный в PATCH запрос.

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

Например, следующий PATCH запрос интерпретируется как запрос на обновление только атрибутов "title" и "text" статьи:

PATCH /articles/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "To TDD or Not",
      "text": "TLDR; It's complicated... but check your test coverage regardless."
    }
  }
}

7.2.2 Обновление связей ресурса

Любые или все отношения ресурса МОГУТ быть включены в объект ресурса, включенный в PATCH запрос.

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

Если связь указана в элементе "relationships" объекта ресурса в PATCH запросе, ее значением ДОЛЖЕН быть объект связи с элементом данных. Значение связи будет заменено значением, указанным в этом элементе.

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

PATCH /articles/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "articles",
    "id": "1",
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "1" }
      }
    }
  }
}

Аналогично, следующий PATCH запрос выполняет полную замену тегов для статьи:

PATCH /articles/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "articles",
    "id": "1",
    "relationships": {
      "tags": {
        "data": [
          { "type": "tags", "id": "2" },
          { "type": "tags", "id": "3" }
        ]
      }
    }
  }
}

Сервер МОЖЕТ отклонить попытку выполнить полную замену отношения "ко многим". В таком случае сервер ДОЛЖЕН отклонить все обновление и вернуть ответ "403 Forbidden".

Примечание: Поскольку полная замена может быть очень опасной операцией, сервер может запретить ее. Например, сервер может отклонить полную замену, если он не предоставил клиенту полный список связанных объектов и не хочет разрешать удаление записей, которые клиент не видел.

7.2.3 Ответы

7.2.3.1 202 Accepted
Если запрос на обновление был принят для обработки, но обработка не была завершена к моменту ответа сервера, сервер ДОЛЖЕН вернуть код состояния 202 Принято.

7.2.3.2 200 OK
Если сервер принимает обновление, но также изменяет ресурсы способами, отличными от указанных в запросе (например, обновляет атрибут updated-at или вычисленный sha), он ДОЛЖЕН вернуть ответ 200 OK. Документ ответа ДОЛЖЕН включать представление обновленных ресурсов, как если бы на URL-адрес запроса был отправлен запрос GET.

Сервер ДОЛЖЕН вернуть код состояния 200 OK, если обновление прошло успешно, текущие поля клиента остаются актуальными, и сервер отвечает только метаданными верхнего уровня. В этом случае сервер НЕ ДОЛЖЕН включать представление обновленных ресурсов.

7.2.3.3 204  204 No Content
Если обновление прошло успешно и сервер не обновляет никаких полей, кроме предоставленных, сервер ДОЛЖЕН вернуть либо код состояния 200 OK и документ ответа (как описано выше), либо код состояния  204 No Content без тела ответа.

7.2.3.4 403 Forbidden
Сервер ДОЛЖЕН вернуть 403 Forbidden в ответ на неподдерживаемый запрос на обновление ресурса или отношения.

7.2.3.5 404 Not Found
Сервер ДОЛЖЕН возвращать 404 Not Found при обработке запроса на изменение несуществующего ресурса.

Сервер ДОЛЖЕН возвращать 404 Not Found при обработке запроса, который ссылается на связанный ресурс, который не существует.

7.2.3.6 409 Conflict
Сервер МОЖЕТ вернуть 409 Conflict при обработке запроса на PATCH для обновления ресурса, если это обновление нарушит другие ограничения, применяемые сервером (например, ограничение уникальности для свойства, отличного от id).

Сервер ДОЛЖЕН возвращать конфликт 409 при обработке запроса на PATCH , в котором тип и идентификатор объекта ресурса не соответствуют конечной точке сервера.

Сервер ДОЛЖЕН содержать подробные сведения об ошибке и предоставлять достаточно информации, чтобы распознать источник конфликта.

7.2.3.7 Прочие Ответы

Сервер МОЖЕТ отвечать другими кодами состояния HTTP.

Сервер МОЖЕТ включать сведения об ошибках с ответами на ошибки.

Сервер ДОЛЖЕН подготовить ответы, а клиент ДОЛЖЕН интерпретировать ответы в соответствии с семантикой HTTP.

7.3 Обновление Связей

Хотя отношения могут быть изменены вместе с ресурсами (как описано выше), JSON:API также поддерживает обновление отношений независимо по URL-адресам из ссылок на отношения.

Примечание. Связи обновляются без раскрытия семантики базового сервера, такой как внешние ключи. Кроме того, отношения могут быть обновлены без обязательного влияния на соответствующие ресурсы. Например, если в статье много авторов, можно удалить одного из авторов из статьи, не удаляя самого автора. Аналогично, если статья содержит много тегов, можно добавлять или удалять теги. Под капотом на сервере первый из этих примеров может быть реализован с помощью внешнего ключа, в то время как второй может быть реализован с помощью таблицы соединений, но протокол JSON:API будет одинаковым в обоих случаях.

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

7.3.1 Обновление связей "к одному"

Сервер ДОЛЖЕН отвечать на PATCH запросы по URL-адресу из ссылки связи "один к одному", как описано ниже.

Запрос на ИСПРАВЛЕНИЕ ДОЛЖЕН включать элемент верхнего уровня с именем data, содержащий один из:

• объект идентификатора ресурса, соответствующий новому связанному ресурсу.
• null, чтобы удалить связь.

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

PATCH /articles/1/relationships/author HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": { "type": "people", "id": "12" }
}

И следующий запрос очищает автора той же статьи:

PATCH /articles/1/relationships/author HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": null
}

Если связь успешно обновлена, сервер ДОЛЖЕН вернуть успешный ответ.

7.3.2 Обновление связей "ко многим"

Сервер ДОЛЖЕН отвечать на запросы на PATCH, POST и DELETE по URL-адресу из ссылки "многим", как описано ниже.

Для всех типов запросов тело ДОЛЖНО содержать элемент "data", значением которого является пустой массив или массив объектов идентификаторов ресурсов.

Если клиент отправляет запрос PATCH по URL-адресу из ссылки связи "многим", сервер ДОЛЖЕН либо полностью заменить каждого участника связи, вернуть соответствующий ответ об ошибке, если некоторые ресурсы не могут быть найдены или доступны, либо вернуть ответ "403 Forbidden", если полная замена не разрешена сервером.

Например, следующий запрос заменяет каждый тег для статьи:

PATCH /articles/1/relationships/tags HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": [
    { "type": "tags", "id": "2" },
    { "type": "tags", "id": "3" }
  ]
}

И следующий запрос очищает каждый тег для статьи:

PATCH /articles/1/relationships/tags HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": []
}

Если клиент делает запрос POST на URL-адрес из ссылки связи, сервер ДОЛЖЕН добавить указанных участников в связь, если они еще не присутствуют. Если данный "type" и "id" уже связаны, то сервер НЕ ДОЛЖЕН добавлять их снова.

Примечание: Это соответствует семантике баз данных, которые используют внешние ключи для отношений "имеет много". Хранилище на основе документов должно проверять взаимосвязь "имеет много" перед добавлением, чтобы избежать дублирования.

Если все указанные ресурсы могут быть добавлены или уже присутствуют в отношениях, то сервер ДОЛЖЕН вернуть успешный ответ.

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

В следующем примере комментарий с идентификатором 123 добавляется в список комментариев к статье с идентификатором 1:

POST /articles/1/relationships/comments HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": [
    { "type": "comments", "id": "123" }
  ]
}

Если клиент делает запрос DELETE на URL-адреса из ссылки связи, сервер ДОЛЖЕН удалить указанных участников из связи или вернуть ответ "403 Forbidden". Если все указанные ресурсы могут быть удалены из связи или уже отсутствуют в ней, сервер ДОЛЖЕН вернуть успешный ответ.

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

Элементы связей указываются так же, как и в POST запросе .

В следующем примере комментарии с идентификаторами 12 и 13 удаляются из списка комментариев к статье с идентификатором 1:

DELETE /articles/1/relationships/comments HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": [
    { "type": "comments", "id": "12" },
    { "type": "comments", "id": "13" }
  ]
}

Примечание: RFC 7231 указывает, что запрос на удаление может содержать тело, но сервер может отклонить запрос. Эта спецификация определяет семантику сервера, и мы определяем ее семантику для JSON:API.

7.3.3 Ответы

7.3.3.1 202 Accepted
Если запрос на обновление отношений был принят для обработки, но обработка не была завершена к моменту ответа сервера, сервер ДОЛЖЕН вернуть код состояния 202 Accepted.

7.3.3.2 204 No Content
Сервер ДОЛЖЕН вернуть код состояния "204 No Content", если обновление прошло успешно и представление ресурса в запросе соответствует результату.

Примечание: Это соответствующий ответ на запрос POST, отправленный на URL-адрес по ссылке "многим", когда эта связь уже существует. Это также подходящий ответ на запрос на удаление, отправленный по URL-адресу из ссылки "многим", когда эта связь не существует.

7.3.3.3 200 ОК
Если сервер принимает обновление, но также изменяет целевые отношения другими способами, отличными от указанных в запросе, он ДОЛЖЕН вернуть ответ 200 OK. Документ ответа ДОЛЖЕН включать представление обновленных отношений.

Сервер ДОЛЖЕН вернуть код состояния 200 OK, если обновление прошло успешно, текущие данные клиента остаются актуальными, и сервер отвечает только метаданными верхнего уровня. В этом случае сервер НЕ ДОЛЖЕН включать представление обновленных отношений.

7.3.3.4 403 Forbidden
Сервер ДОЛЖЕН вернуть "403 Forbidden" в ответ на неподдерживаемый запрос на обновление связи.

7.3.3.5 Прочие Ответы

Сервер МОЖЕТ отвечать другими кодами состояния HTTP.

Сервер МОЖЕТ включать сведения об ошибках с ответами на ошибки.

Сервер ДОЛЖЕН подготовить ответы, а клиент ДОЛЖЕН интерпретировать ответы в соответствии с семантикой HTTP.

7.4 Удаление ресурсов

Отдельный ресурс можно удалить, отправив запрос DELETE по URL-адресу ресурса:

DELETE /photos/1 HTTP/1.1
Accept: application/vnd.api+json

7.4.1 Ответы

7.4.1.1 202 Accepted
Если запрос на удаление был принят для обработки, но обработка не была завершена к моменту ответа сервера, сервер ДОЛЖЕН вернуть код состояния 202 Accepted.

7.4.1.2 204 No Content
Сервер ДОЛЖЕН вернуть код состояния 204 No Content, если запрос на удаление выполнен успешно и содержимое не возвращено.

7.4.1.3 200 ОК
Сервер ДОЛЖЕН вернуть код состояния 200 OK, если запрос на удаление выполнен успешно и сервер отвечает только метаданными верхнего уровня.

7.4.1.4 404 NOT FOUND
Сервер ДОЛЖЕН возвращать код состояния 404 NOT FOUND, если запрос на удаление не выполняется из-за отсутствия ресурса.

7.4.1.5 Прочие Ответы

Сервер МОЖЕТ отвечать другими кодами состояния HTTP.

Сервер МОЖЕТ включать сведения об ошибках с ответами на ошибки.

Сервер ДОЛЖЕН подготовить ответы, а клиент ДОЛЖЕН интерпретировать ответы в соответствии с семантикой HTTP.

8. Параметры запроса

Параметры запроса, специфичные для реализации, ДОЛЖНЫ соответствовать тем же ограничениям, что и имена элементов, с дополнительным требованием, чтобы они содержали по крайней мере один символ, отличный от a-z (от U+0061 до U+007A). РЕКОМЕНДУЕТСЯ использовать ДЕФИС  U+002D HYPHEN-MINUS, "-", U+005F LOW LINE, "_" или заглавные буквы (например, ВерблюжийСтиль).

Если сервер обнаруживает параметр запроса, который не соответствует приведенным выше соглашениям об именовании, и сервер не знает, как обработать его в качестве параметра запроса из этой спецификации, он ДОЛЖЕН вернуть "400 Bad Request".

Примечание: Это делается для сохранения способности JSON:API вносить дополнительные дополнения в стандартные параметры запроса, не вступая в противоречие с существующими реализациями.

9 Ошибки

9.1 Обработка ошибок

Сервер МОЖЕТ остановить обработку, как только возникнет проблема, или он МОЖЕТ продолжить обработку и столкнуться с несколькими проблемами. Например, сервер может обрабатывать несколько атрибутов, а затем возвращать несколько проблем с проверкой в одном ответе.

Когда сервер сталкивается с несколькими проблемами для одного запроса, в ответе СЛЕДУЕТ использовать наиболее распространенный код ошибки HTTP. Например, "400 Bad Request" может быть подходящими для нескольких ошибок 4xx или "500 Internal Server Error" могут быть подходящими для нескольких ошибок 5xx.

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

Объекты ошибок предоставляют дополнительную информацию о проблемах, возникших при выполнении операции. Объекты ошибок ДОЛЖНЫ быть возвращены в виде массива, в элементе "errors" на верхнем уровне документа JSON:API.

Объект ошибки МОЖЕТ содержать следующие элементы:

• id: уникальный идентификатор для данного конкретного случая проблемы.
• links: объект ссылок, содержащий следующие элементы:
  • about: ссылка, которая ведет к более подробной информации об этом конкретном случае проблемы.
• status: код состояния HTTP, применимый к этой проблеме, выраженный в виде строкового значения.
• code: код ошибки конкретного приложения, выраженный в виде строкового значения.
• title: краткое, понятное для человека краткое описание проблемы, которое НЕ ДОЛЖНО меняться от возникновения к возникновению проблемы, за исключением целей локализации.
• detail: понятное для человека объяснение, специфичное для этого случая проблемы. Как и заголовок, значение этого поля может быть локализовано.
• source: объект, содержащий ссылки на источник ошибки, необязательно включающий любой из следующих элементов:
  • pointer: указатель JSON [RFC6901] на связанный объект в документе запроса [например, "/data" для основного объекта данных или "/data/attributes/title" для определенного атрибута].
  • parameter: строка, указывающая, какой параметр запроса URI вызвал ошибку.
• meta: мета-объект, содержащий нестандартную мета-информацию об ошибке.