Как смоделировать RESTful API с наследованием?

У меня есть иерархия объектов, которую мне нужно раскрыть через RESTful API, и я не уверен, как должны быть структурированы мои URL-адреса и что они должны возвращать. Я не смог найти лучших практик.

Скажем, у меня есть собаки и кошки, унаследованные от животных. Мне нужны CRUD-операции собакам и кошкам; Я также хочу иметь возможность делать операции с животными в целом.

Первой моей идеей было сделать что-то вроде этого:

GET /animals        # get all animals
POST /animals       # create a dog or cat
GET /animals/123    # get animal 123

Дело в том, что коллекция / animals теперь «несовместима», так как она может возвращать и принимать объекты, которые не имеют точно такой же структуры (собаки и кошки). Считается ли "RESTful" иметь коллекцию, возвращающую объекты с разными атрибутами?

Другое решение - создать URL-адрес для каждого конкретного типа, например:

GET /dogs       # get all dogs
POST /dogs      # create a dog
GET /dogs/123   # get dog 123

GET /cats       # get all cats
POST /cats      # create a cat
GET /cats/123   # get cat 123

Но теперь отношения между собаками и кошками потеряны. Если кто-то хочет получить всех животных, необходимо запросить ресурсы собаки и кошки. Количество URL-адресов также будет увеличиваться с каждым новым подтипом животных.

Другое предложение заключалось в том, чтобы дополнить второе решение, добавив следующее:

GET /animals    # get common attributes of all animals

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

Есть комментарии или предложения?

Я бы посоветовал:

• Использование только одного URI для каждого ресурса
• Дифференциация между животными исключительно на уровне атрибутов

Установка нескольких URI для одного ресурса никогда не является хорошей идеей, поскольку это может вызвать путаницу и неожиданные побочные эффекты. Учитывая это, ваш единственный URI должен быть основан на общей схеме, например /animals.

Следующая задача - иметь дело со всем набором собак и кошек на «базовом» уровне уже решена благодаря /animalsподходу URI.

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

GET /animals( Accept : application/vnd.vet-services.animals+json)

{
   "animals":[
      {
         "link":"/animals/3424",
         "type":"dog",
         "name":"Rex"
      },
      {
         "link":"/animals/7829",
         "type":"cat",
         "name":"Mittens"
      }
   ]
}

• GET /animals - получает всех собак и кошек, вернет и Рекса, и варежек
• GET /animals?type=dog - получает всех собак, вернет только Рекса
• GET /animals?type=cat - заводит всех кошек, бы только варежки

Затем при создании или изменении животных вызывающий должен будет указать тип задействованного животного:

Тип СМИ: application/vnd.vet-services.animal+json

{
   "type":"dog",
   "name":"Fido"
}

Вышеуказанная полезная нагрузка может быть отправлена ​​с помощью запроса POSTили PUT.

Вышеупомянутая схема дает вам основные характеристики, аналогичные OO-наследованию через REST, и с возможностью добавления дополнительных специализаций (т.е. большего количества типов животных) без серьезных операций или каких-либо изменений в вашей схеме URI.

На этот вопрос можно лучше ответить с помощью недавнего улучшения, представленного в последней версии OpenAPI.

Было возможно комбинировать схемы, используя такие ключевые слова, как oneOf, allOf, anyOf, и получать полезные данные сообщения, проверенные с момента появления схемы JSON v1.0.

https://spacetelescope.github.io/understanding-json-schema/reference/combining.html

Однако в OpenAPI (бывший Swagger) композиция схем была улучшена за счет использования ключевых слов дискриминатор (v2.0 +) и oneOf (v3.0 +) для полной поддержки полиморфизма.

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaComposition

Ваше наследование может быть смоделировано с помощью комбинации oneOf (для выбора одного из подтипов) и allOf (для объединения типа и одного из его подтипов). Ниже приведен пример определения метода POST.

paths:
  /animals:
    post:
      requestBody:
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/Dog'
              - $ref: '#/components/schemas/Cat'
              - $ref: '#/components/schemas/Fish'
            discriminator:
              propertyName: animal_type
     responses:
       '201':
         description: Created

components:
  schemas:
    Animal:
      type: object
      required:
        - animal_type
        - name
      properties:
        animal_type:
          type: string
        name:
          type: string
      discriminator:
        property_name: animal_type
    Dog:
      allOf:
        - $ref: "#/components/schemas/Animal"
        - type: object
          properties:
            playsFetch:
              type: string
    Cat:
      allOf:
        - $ref: "#/components/schemas/Animal"
        - type: object
          properties:
            likesToPurr:
              type: string
    Fish:
      allOf:
        - $ref: "#/components/schemas/Animal"
        - type: object
          properties:
            water-type:
              type: string

Я бы пошел на / animals, возвращающий список собак и рыб, а также что-либо еще:

<animals>
  <animal type="dog">
    <name>Fido</name>
    <fur-color>White</fur-color>
  </animal>
  <animal type="fish">
    <name>Wanda</name>
    <water-type>Salt</water-type>
  </animal>
</animals>

Реализовать аналогичный пример JSON должно быть легко.

Клиенты всегда могут рассчитывать на наличие элемента «имя» (общий атрибут). Но в зависимости от атрибута «тип» в представлении животного могут быть и другие элементы.

В возвращении такого списка нет ничего по сути RESTful или unRESTful - REST не предписывает какой-либо конкретный формат для представления данных. Все, что он говорит, - это то, что данные должны иметь некоторое представление, и формат для этого представления определяется типом носителя (который в HTTP является заголовком Content-Type).

Подумайте о своих сценариях использования - вам нужно показать список смешанных животных? Что ж, тогда верните список смешанных данных о животных. Вам нужен только список собак? Что ж, составьте такой список.

Независимо от того, используете ли вы / animals? Type = dog или / dogs, это не имеет отношения к REST, который не предписывает какие-либо форматы URL-адресов - это оставлено в качестве детали реализации за пределами REST. REST только указывает, что ресурсы должны иметь идентификаторы - неважно в каком формате.

Вам следует добавить гиперссылки, чтобы приблизиться к RESTful API. Например, добавив ссылки на сведения о животных:

<animals>
  <animal type="dog" href="https://stackoverflow.com/animals/123">
    <name>Fido</name>
    <fur-color>White</fur-color>
  </animal>
  <animal type="fish" href="https://stackoverflow.com/animals/321">
    <name>Wanda</name>
    <water-type>Salt</water-type>
  </animal>
</animals>

Добавляя гиперссылки, вы уменьшаете взаимосвязь между клиентом и сервером - в приведенном выше случае вы снимаете с клиента бремя создания URL-адресов и позволяете серверу решать, как создавать URL-адреса (которые он по определению является единственным органом власти).

Но теперь отношения между собаками и кошками потеряны.

Действительно, но имейте в виду, что URI просто никогда не отражает отношения между объектами.

Я знаю, что это старый вопрос, но мне интересно изучить дальнейшие вопросы моделирования наследования RESTful.

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

ПОЛУЧИТЬ животные /: animalID / яйца

не согласуется, потому что указывает на то, что все подтипы животных могут иметь яйца (как следствие замещения Лискова). Если все млекопитающие ответят «0» на этот запрос, произойдет откат, но что, если я также включу метод POST? Стоит ли бояться, что завтра в моих блинчиках будут собачьи яйца?

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

GET / animals /: animalID / sons GET / hens /: animalID / яйца POST / hens /: animalID / яйца

Недостатком здесь является то, что кто-то может передать идентификатор собаки для ссылки на экземпляр коллекции кур, но собака не является курицей, поэтому было бы неправильно, если бы ответ был 404 или 400 с сообщением о причине.

Я ошибся?

Да ты ошибаешься. Также отношения могут быть смоделированы в соответствии со спецификациями OpenAPI, например, таким полиморфным способом.

Chicken:
  type: object
  discriminator:
    propertyName: typeInformation
  allOf:
    - $ref:'#components/schemas/Chicken'
    - type: object
      properties:
        eggs:
          type: array
          items:
            $ref:'#/components/schemas/Egg'
          name:
            type: string

...