Подскажите, пожалуйста, как правильно составлять эндпойнты на примере задачи? Есть научный портал. Основной сущностью портала являются научные статьи. У статей есть авторы. Статьи содержат следующие характеристики: название, год написания, автор. Автор: имя, в каком ВУЗе учится/работает. Необходимо написать спецификацию для API научного портала, который будет выполнять следующий функционал для сущностей: Статьи: получение всех статьи, получение определенной статьи по идентификатору, получение статьи по имени автора, добавление статьи, изменение данных статьи, удаление статьи. Авторы: получение всех авторов в портале, изменение данных авторов, добавление новых авторов, удаление авторов, получение всех статей автора, получение автора с определенным идентификатором.
Но есть советы к задаче, которыми нужно воспользоваться, если в этом есть смысл.
Используйте вложения там где это нужно.
Не используйте вложения больше второго уровня.
Я хочу сделать эндпойнт articles отдельно, и authors отдельно. То есть чтобы получить все статьи, мы используем GET запрос /articles, а чтобы поучить всех авторов, то GET запрос /authors. Но проблема заключается в гайдлане, а именно в первом совете использовать вложения там, где это нужно. И так же в условии явно описано, что главная сущность тут статьи, а авторы как бы относятся к этой сущности. Я думаю, что может быть можно сделать такой вариант: /articles - все статьи /articles/authors все авторы Но тогда, чтобы получить все статьи определённого автора, придётся писать не authors/{id}/articles а /articles/authors/{id}/articles что выглядит глупо, так как мы от статей переходим к авторам, а от авторов опять к статьям. Или может все таки первый совет про вложенности тут можно использовать?
Так же я хотел бы уточнить про уровни вложенности. Как их считать? Параметр считается за уровень? Вроде /articles/{name_authors} тут один или два уровня? А операции в эндпойнтах считаются за уровень? product/comments/{id}/text имеет три уровня вложенности или два? Ведь "text" - это операция, которая говорит, что нужно получить текст комментария товара. Ещё вопрос, что делать с большими вложенностями? Что делать, если вложенность становится больше двух уровней?
И еще вопрос, в Swagger мы можем описать компонент в виде JSON формата, чтобы ссылать на него в путях. Пример:
"components": {
"schemas": {
"Article": {
"type": "object",
"properties": {
"article_id": {
"type": "integer",
"format": "int64",
"example": 445
},
"title": {
"type": "string",
"example": "Название статьи"
},
"year": {
"type": "integer",
"format": "int32",
"example": 2020
}
}
}
для GET такой компонент подходит, но в requestBody метода POST для добавления новой статьи, как мне кажется, нет, так как пользователь не должен вводить ID статьи, ведь она приписывается автоматически. Тогда для этого случая сделать компонент ArticleWithoutID без ID и ссылаться в методе POST на него?
