Блог

Главная - Вопросы по программированию - Запрашивать допустимые атрибуты в JSON: спецификация API

Запрашивать допустимые атрибуты в JSON: спецификация API

#json-api

#json-api

Вопрос:

Я хочу использовать JSON: API для моих новых REST API. Спецификация звучит хорошо, и все в порядке. Единственное, чего мне не хватает, — это способа запросить допустимые атрибуты для объекта.

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

Пример

Запрос на получение списка статей

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

Ответ (с нулевыми статьями)

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

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

=> Здесь мне не хватает вызова извлечения доступных атрибутов для нового объекта article <=

Запрос на создание статьи

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

{
  "data": {
    "type": "articles",
    "attributes": {
      "title": "New Article" <= i have to know this attribute
    }
  }
}

Ответ №1:

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

Например, вы могли бы предоставить интерфейс OpenAPI (ранее Swagger) для предоставления машиночитаемой информации о типах и документации для всего вашего API.

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

Ваш вопрос частично подразумевает, что вы могли бы получить схему ресурса на основе объекта ресурса. Я бы не рекомендовал это делать:

  • Объект ресурса может содержать не все поля. Некоторые файлы могут быть скрыты из-за использования разреженного набора полей. Или сервер может включать не все поля по умолчанию.
  • Атрибут может поддерживать несколько значений. Например null , может быть допустимым значением, даже если атрибут является строкой для одного ресурсного объекта.
  • В дополнение к тому, что атрибут имеет тот же тип, может потребоваться соблюдение правил проверки. Например. атрибут даты может быть закодирован как строка "2020-01-01T00:00:00.000Z" в JSON. Но это не означает, что все строки являются допустимыми значениями для этого атрибута.