Проектирование REST API — это тема для постоянных споров «как правильно?». Вопросы с подвохами любят давать на собеседованиях для Backend‑разработчиков, архитекторов и системных аналитиков.

Как понять, что мы проектируем REST API правильно? Никак. Смотреть на публичную API‑документацию крупных систем, диссертацию Роя Филдинга, или на то, что уже есть в проекте. И исходя из этого принимать решения о том, как будут выглядеть новые REST API методы.

В этой статье я хочу представить результаты исследований REST API сервисов управления задачами Trello и Todoist, чтобы показать, какие решения являются хорошими стандартами проектирования, а какие нет, но их всё равно применяют на практике.

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

Введение:

• Краткий обзор Trello

• Краткий обзор Todoist

• Теория по REST API

Спорные вопросы:

1. Какой HTTP-код ответа на метод POST: 200 или 201?

2. Какой метод лучше использовать для редактирования данных: POST, PUT или PATCH?

3. Как правильно строить структуру URL запросов (эндпоинтов)?

4. Как правильно именовать эндпоинты — ед. число или мн. число (/task или /tasks)?

5. Как строить эндпоинт и body в REST API методе, если нам нужно создать задачу, и она должна быть создана внутри проекта?

6. Что вернуть в ответ на запрос списка, если ничего не найдено — пустой массив или HTTP-404?

7. Какой код вернуть в ответ на запрос DELETE?

8. Может ли быть у DELETE тело запроса?

9. Чем отличается REST от RESTful API?

Эта статья является логическим продолжением «Проектирование REST API: спорные вопросы с проектов и собеседований на системного аналитика (и не только)» и поможет ещё лучше разобраться в этой теме.

Введение

Для анализа спорных вопросов я специально взяла две публичных REST API документации, то есть:

• Они доступны онлайн, бесплатно и без СМС.

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

Trello и Todoist предназначены для управления проектами, как личными, так и рабочими. Упрощенные аналоги системы Jira Attlassian.

Краткий обзор Trello

Trello — это визуальный инструмент для управления задачами и проектами, основанный на системе канбан‑досок.

• Пользователь регистрируется и входит в систему.

• Создаёт доски - boards.

• Создает списки (колонки, листы) на доске - lists, они отвечают за статусы задач.

• Создаёт карточки в этих колонках - cards, они же задачи.

• К карточкам можно оставлять комментарии - comments.

Публичная REST API документация:

• Общий обзор и порядок авторизации запросов

• REST API методы — основной документ, который будем исследовать

Краткий обзор Todoist

Todoist — это планировщик задач, который помогает пользователям организовывать личные и командные задачи с системой приоритетов, напоминаний и дедлайнов.

• Пользователь регистрируется и входит в систему.

• Создаёт проекты - projects.

• Создает задачи внутри проектов - tasks.

• К задачам можно оставлять комментарии - comments.

Публичная REST API документация:

• Введение, про авторизацию и рекомендации по использованию

• REST API методы

Теория по REST API

Теорию по REST API я разбирала на примере проекта онлайн-библиотеки ElibraGA в мини-статьях:

• Структура методов REST API

• Назначение HTTP-методов: GET, POST, PUT, PATCH, DELETE

• Проектирование эндпоинтов - структура URL

• Headers в HTTP / REST API

• Книга по JSON в REST API

• Ошибки проектирования методов REST API - подборка с примерами

• Методы REST API: 9 примеров для понимания принципов дизайна REST API

На что хочу обратить внимание:

• Если API на все 100% соответствует архитектурному стилю REST, то его обычно называют RESTful API.

• Если API частично соответствует архитектурному стилю REST, но некоторые принципы нарушены, то его обычно называют REST API.

Спорные вопросы по REST API

1. Какой HTTP-код ответа на метод POST: 200 или 201?

При правильном подходе к использованию метода POST для создания новых данных в БД рекомендуется на успешные операции отвечать HTTP-201 Created. Хотя HTTP-200 ОК тоже допустим, когда в результате выполнения запроса новые данные не создаются.

Примеры запросов POST в документации Trello:

• POST /boards - создать доску - код успешного ответа на создание доски HTTP-200.

• POST /lists - создать лист - код успешного ответа HTTP-200.

• POST /cards - создать карточку - код успешного ответа HTTP-200.

Получается, что ответы на все методы POST — HTTP-200 OK, хотя согласно стандарту протокола HTTP и выбору статус-кодов для ответа должен быть HTTP-201 Created (created = создано).

Если посмотреть другие методы REST API Trello, которые связаны с получением GET, удалением DELETE или редактированием данных PUT, то можно увидеть, что на все успешные запросы возвращается ответ HTTP-200.

Является ли это ошибкой или причиной неработоспособности REST API?
Нет. Просто так решили разработчики и считают, что так удобно его пользователям.

Теперь посмотрим на запросы POST в документации Todoist:

• POST /projects - создать проект - код успешного ответа HTTP-200.

• POST /tasks - создать задачу - код успешного ответа HTTP-200.

• POST /comments - создать комментарий к задаче - код успешного ответа HTTP-200.

Посмотрели на два разных API и в обоих одинаковая ошибка. Это может ввести в заблуждение и заставить сомневаться.

Согласно протоколу HTTP есть набор стандартных статус-кодов. HTTP-201 предназначен для ответа на запрос, который создаёт новые данные в БД, новую сущность (новую строку в основной таблице БД, для которой метод, и связанные с ней данные).

Примеры реализации с кодом HTTP-201 на метод POST есть в:

Avito API - метод публикации новой вакансии

POST https://api.avito.ru/job/v1/vacancies

Atlassian REST API - метод создания новой задачи в Jira (и это при том, что и Trello, и Jira владеет одна компания - Atlassian)

POST /rest/api/3/issue

Sber API - создание зарплатной ведомости

POST /fintech/api/v1/payrolls

При использовании метода POST для создания новых ресурсов в вашем RESTful API рекомендуется ответ с кодом 201 Created.

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

Просто получается, что ни REST API Trello, ни REST API Todoist не отвечают стандартам RESTful API и возвращают HTTP-200 на все запросы, даже если это создание данных в БД.

Итого:

• Trello: +1 нарушение принципа RESTful API

• Todoist: +1 нарушение принципа RESTful API

2. Какой метод лучше использовать для редактирования данных: POST, PUT или PATCH?

Для разбора этого вопроса мне пришлось прибегнуть к тестированию API через Postman, чтобы понять, как на самом деле работают методы, т.к. один частично соблюдает рекомендации REST API, а второй не соблюдает их совсем и непонятно было, что от него ждать.

Назначение методов согласно протоколу HTTP и архитектурному стилю REST API:

• POST: Создание нового объекта данных.

• PUT:

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

  • Создание новых данных в БД, если по ключу идемпотентности.

• PATCH: Частичное изменение данных об объекте. Обновляются только те данные, которые переданы на вход. Остальные параметры сущности остаются без изменений.

В документации Trello:

• PUT /boards/{id} - редактировать выбранную по {id} доску

• PUT /cards/{id} - редактировать выбранную по {id} карточку

PUT предназначен для полного обновления ресурсов (объектов данных в БД / строк в БД).

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

Проведём тестирование REST API от Trello через Postman.

Результат тестирования REST API Trello через Postman

1.Создаю новую доску через POST /boards. На вход переданы название и описание.
https://developer.atlassian.com/cloud/trello/rest/api-group-boards/#api-boards-post

2.Редактирую название доски, но при этом описание не передаю.
Согласно логике метода PUT, которая ожидается согласно рекомендациям REST API, то объект пересоздаётся полностью.

А значит я ожидаю, что после вызова метода описание доски удалится, так как оно не передается на вход.

Но нет. Оно осталось целым и невредимым.

3.Как же зачистить описание доски, если оно мне не нужно?
Пробуем передать на вход пустую строку и всё получается.

Дополнительно хотела проверить, что можно зачистить значение, передав null, но null на вход методу воспринялся как строка данных.

Получается, что поле description не поддерживает null (как тип данных "пустое значение" в JSON). Проверила это, вызвав создание доски с пустым описанием, и увидела, что в ответе "desc": "". Это ожидаемое поведение.

Выводы по PUT в REST API Trello:

• PUT предназначен для редактирования данных - это ожидаемо.

• PUT предназначен ТОЛЬКО для редактирования данных - создавать новые доски через него нельзя, так как в URL присутствует идентификатор конкретной доски, которую хотим редактировать. И если он не найден, то вернется HTTP-404 с текстом "The requested resource was not found".

• Согласно REST API ожидалось, что при отсутствии одного из параметров объекта он будет автоматически очищен. Но это не так. На примере с desc увидели, что те параметры, которые не передаются на вход запросу, не меняются. Это действительно хорошая реакция, но она соответствует методу PATCH, но не PUT.

Получается, что API Trello снова нарушает принципы архитектурного стиля REST по использованию PUT. Но! Их нарушает минимум половина проектов по всему миру.

Более половины REST API, с которыми мне удалось работать как для интеграций, так и в разработке, имели подход использовать PUT как PATCH. Почему так? Исторически сложилось.

В документации Todoist:

• POST /projects/{id} - редактировать выбранный по id проект

• POST /tasks/{id} - редактировать выбранную по id задачу

Без комментариев. Это явное отклонение от REST. Метод POST это про создание данных, но никак не про редактирование.

Работать он будет так же как и PUT в Trello - меняется только то, что передано на вход.

Результат тестирования REST API Todoist через Postman

1.Вызываю метод создания проекта POST /projects.
https://developer.todoist.com/rest/v2/#create-a-new-project

2.Вызываю метод редактирования созданного проекта, передавая на вход только имя, но не передавая цвет. Меняется только имя. Не самый удачный пример, но суть понятна - меняются только те данные, которые переданы на вход, весь объект данных не обновляется.

Итого:

• Trello: всё почти ок, хотя принцип RESTful API соблюден только частично.

• Todoist: +1 нарушение принципа RESTful API.

Для редактирования лучше использовать метод PATCH. Но на практике встречается много реализации с PUT.

А вот если говорить о POST, то так лучше не надо, но можно.

3. Как правильно строить структуру URL запросов (эндпоинтов)?

Сначала покажу картинку с рекомендацией. Все варианты по построению URL можно найти здесь.

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

Разобрать хочу не только REST API Trello и Todoist, но и несколько других проектов, которые уже упомянула в этой статье.

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

• указание на каталог API на сервере:

  • под api выделяют отдельный поддомен: api.application.com

  • либо внедряют слово api в путь к эндпоинту, до версии.

• версию API рекомендуется внедрять всегда, даже если версии пока не предполагаются.

Итог:

• Trello: придерживается рекомендации по структуре URL.

• Todoist: придерживается рекомендации по структуре URL.

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

4. Как правильно именовать эндпоинты — ед. число или мн. число (/task или /tasks)?

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

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

Пример с ед. числом:
https://yandex.ru/dev/rasp/doc/ru/reference/nearest-settlement

Пример с мн. числом:
https://yandex.ru/dev/market/partner-api/doc/ru/overview/express

Но такая же история оказалась и в Atlassian с Trello и Jira! :)

Два разных продукта в компании. Две разных команды. Два разных решения. И это нормально.

Пример с ед. числом в Jira:
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-projects/#api-rest-api-3-project-projectidorkey-put

Пример с мн. числом:
https://developer.atlassian.com/cloud/trello/rest/api-group-boards/#api-boards-id-put

Давайте сделаем вывод что лучше используется чаще, исходя из анализа всех API, которые рассматриваются в моих статьях.

Единственное число:

• Яндекс Погода: https://yandex.ru/dev/rasp/doc/ru/reference/nearest-settlement

• Atlassian Jira: https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-users/#api-rest-api-3-user-post

Множественное число:

• Яндекс Экспресс: https://yandex.ru/dev/market/partner-api/doc/ru/overview/express

• Atlassian Trello: https://developer.atlassian.com/cloud/trello/rest/api-group-boards/#api-boards-post

• Todoist: https://developer.todoist.com/rest/v2/#create-a-new-project

• Avito: https://developers.avito.ru/api-catalog/job/documentation#operation/vacancyCreate

• Sber: https://developers.sber.ru/docs/ru/sber-api/specifications/payrolls-post (но у них и единственное число есть в одном месте, что вызывает вопросы https://developers.sber.ru/docs/ru/sber-api/specifications/pay-doc-cur-post - метод POST /fintech/api/v1/pay-doc-cur и все рядом с ним)

• Google Cloud API Design Guide: Resource names ---> Example 1: A storage service has a collection of buckets, where each bucket has a collection of objects

• Microsoft API Guidelines: 7.4.1. POST ---> POST http://api.contoso.com/account1/servers

Итого:

• Trello: мн.ч. для именования эндпоинтов, как в большинстве решений по REST API.

• Todoist: мн.ч. для именования эндпоинтов, как в большинстве решений по REST API.

Стандартом отрасли для именования эндпоинтов можно признать множественное число, хотя я до сих пор периодически работаю с единственным числом.

И это не часть архитектурного стиля REST API и не его требование.

5. Как строить эндпоинт и body в REST API методе, если нам нужно создать задачу, и она должна быть создана внутри проекта?

Для начала поясню в чём суть вопроса и что ожидаю увидеть при проектировании вариантов реализации. А затем разберём как сделали в рабочих API Trello и в Todoist.

Для того, чтобы создать задачу в Trello нужно:

• Создать доску (проект)

• Создать лист на доске (категорию / статус)

• Создать задачу (карточку) внутри листа

Наблюдается иерархия: project -> list -> task.

Эту иерархию можно отразить в URL для запросов:

• Создать доску (проект):
  POST /boards

• Создать лист на доске (категорию / статус)
  POST /boards/{boardId}/lists

• Создать задачу (карточку) внутри листа
  POST /boards/{boardId}/lists/{listId}/cards

Проблема такой реализации - слишком длинный URL запроса. Не рекомендуется превышать 6 уровней вложенности. И для метода получить задачу по id - GET /boards/{boardId}/lists/{listId}/tasks/{taskId} их как раз и будет 6.

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

Поэтому чаще всего делают приходят к упрощенному решению:

• Создать доску (проект):
  POST /boards

• Создать лист на доске (категорию / статус)
  POST /lists
  данные по id доски отправляются в body json.

• Создать задачу (карточку) внутри листа
  POST /cards
  данные по id доски и id листа отправляются в body json.

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

Но какая фактическая реализация этих методов согласно документации Trello?

• Создать доску (проект):
  POST /boards
  https://developer.atlassian.com/cloud/trello/rest/api-group-boards/#api-boards-post
  Все параметры с описанием в query, после ? в запросе.

• Создать лист на доске (категорию / статус)
  POST /lists
  https://developer.atlassian.com/cloud/trello/rest/api-group-lists/#api-lists-post
  данные по id доски отправляются в query-параметр, но не в body json:
  POST https://api.trello.com/1/lists?name={name}&idBoard=5abbe4b7ddc1b351ef961414&key=APIKey&token=APIToken
  idBoard - это идентификатор доски.
  Он всё равно остался в URL и занимает символы в нём, не меньше, чем если бы была сделана иерархия в пути запроса.
  Он обязательный, как и параметр в пути запроса.
  Какой смысл был отправлять в query-параметр этот idBoard - неизвестно.
  Но моё субъективное мнение: это не лучшее решение.
  Понизили читаемость.

• Создать задачу внутри листа (карточку)
  POST /cards
  https://developer.atlassian.com/cloud/trello/rest/api-group-cards/#api-cards-post
  Пример:
  POST https://api.trello.com/1/cards?idList=5abbe4b7ddc1b351ef961414&key=APIKey&token=APIToken
  А вот и ответ на вопрос почему отправили idBoard в query.
  Потому что в следующем запросе на создание задачи есть idList, а idBoard, который мог бы занимать место в URL-запроса из-за иерархии уже не нужен. Экономим место и делаем URL-ы предсказуемыми.
  Отмена, решение нормальное.
  Хотя я бы отправляла это в body json, как и все другие параметры необходимые для создания карточки задачи, чтобы не перегружать URL.
  Но в Trello наблюдаю, что все важные параметры внесены в URL, а тело запроса вообще не используется. Нестандартное решение.

А что насчёт API Todoist:

• Создать проект:
  POST /projects
  https://developer.todoist.com/rest/v2/#create-a-new-project
  Все параметры с описанием в body json.

• Создать секцию (необязательно)
  POST /sections
  https://developer.todoist.com/rest/v2/#create-a-new-section
  Данные по id проекта и названию секции отправляются в body json.
  project_id - обязательный параметр в JSON.

• Создать задачу (внутри секции)
  POST /tasks
  https://developer.todoist.com/rest/v2/#create-a-new-task
  Данные по id проекта и id секции отправляются в body json.
  Являются необязательными, и если не указаны, то задача отправится в папку "Входящие" по умолчанию, что раскрыто в API-документации.

Очень хорошее, аккуратное и понятное решение демонстрирует Todoist. Так делают в большинстве REST API проектов.

Итого:

• Trello: решение не противоречит принципам REST API, но имеет недостаток в виде перегруженного URL.

• Todoist: решение не противоречит принципам REST API, имеет простой и понятный URL, все детали скрыты в body JSON.

Если бы я делала очередной Task-трекер, то ориентировалась бы скорее на решение от Todoist, чем от Trello.

В Jira тоже ориентировались на Todoist судя по всему (https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-post - тут всё в теле, включая id проекта)

6. Что вернуть в ответ на запрос списка, если ничего не найдено — пустой массив или HTTP-404?

Этот вопрос заслуживает отдельного комментария от меня (и не только) для всех разработчиков Backend и REST API документации.

Давайте смотреть что есть в наших API для управления задачами.

В Trello я начала искать метод получения списка задач (карточек) в разделе cards. Но не нашла.

Получить можно только карточки внутри доски через метод GET /boards/{id}/cards.

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

По результатам тестирования метода Trello выявлено:

• В ответ на пустой список возвращается код ответа HTTP-200 и пустой массив.

• Если в списке есть карточки, то в массив [] добавляются объекты карточек задач {...}.

• В ответе список с карточками отсутствуют элементы пагинации, что может привести к проблемам при большом количестве задач на доске - длительное ожидание ответа и большой JSON, так как карточек, например, 1000.

Тестирование метода Trello на получение пустого списка карточек проекта

Получаем список карточек на доске, на которой их нет. В ответ возвращается пустой массив: [].
https://developer.atlassian.com/cloud/trello/rest/api-group-boards/#api-boards-id-cards-get

Повторяем запрос после создания одной карточки и получаем в ответ массив [].

Огромный недостаток REST API Trello:
если карточек на доске будет 1000, то они все вернутся сразу, что может значительно увеличить время ответа от сервера.

Нужны элементы пагинации: limit, offset, count.

В Todoist для получения списка задач используется метод GET /tasks.

И в документации всё так же нет описания успешного ответа на пустой список, только один пример успешного ответа. Поэтому Postman нас спасёт.

Тестирование метода Todoist на получение пустого списка карточек проекта

Вызываем метод получения списка задач с фильтром по проекту, которого не существует. Получаем ответ HTTP-200 и пустой массив [].
https://developer.todoist.com/rest/v2/#get-active-tasks

При тестировании метода на получение списка задач, когда они есть в списке - аналогичная проблема как и в Trello с отсутствием элементов пагинации.

Результаты тестирования метода Todoist полностью совпадают с Trello.

Итого:

Распространенным решением по стандарту отрасли является возврат кода ответа HTTP-200 на пустой список, т.к. запрос считается выполненным успешно. Просто результат пустой.

HTTP-404 возвращают, когда мы пытаемся получить объект по id, которого не существует. Пример: GET /tasks/{taskIs}.

Итого:

• Trello: решение по коду ответа HTTP-200 хорошее, но есть недостаток с отсутствием пагинации в ответе.

• Todoist: аналогично Trello.

Оба метода соответствуют рекомендациям REST API и стандарту отрасли. Но я бы рекомендовала дополнительно добавить элементы пагинации в ответ. Хотя в контексте этой предметной области с проектами и задачами можно делать так, как в Trello и Todoist.

{
  "limit": 4,
  "offset": 0,
  "count": 894,
  "objects": [
    {
      "id": 1,
      "name": "..."
    },
    {
      "id": 2,
      "name": "..."
    },
    {
      "id": 3,
      "name": "..."
    },
    {
      "id": 4,
      "name": "..."
    }
  ]
}

7. Какой код вернуть в ответ на запрос DELETE?

Согласно рекомендациям по REST API, которые опубликованы в Mozilla, можно вернуть следующие коды ответов:

• 204 No Content — запрос выполнен успешно, но сервер не отправляет в ответе никаких данных.

• 200 OK — запрос выполнен успешно, и в теле ответа есть данные с описанием результата.

• 202 Accepted — запрос принят, и, скорее всего, будет успешно обработан, но сервер ещё не выполнил удаление ресурса.

Отличные рекомендации! Но в основном почти везде я вижу код ответа HTTP-200 на DELETE.

В Trello метод удаления карточки DELETE /cards/{cardId} возвращает успешный ответ HTTP-200.

В Todoist метод удаления задачи DELETE /tasks/{taskId} возвращает успешный ответ HTTP-204.

В Jira ответ на запрос удаления задачи также ответ HTTP-204.

HTTP-204 означает, что задача на удаления отправляется в очередь к обработке (например, в брокер Kafka) и не держит клиента, пока все данные не будут удалены.

Итого:

Основные ответы, которые используются:

• HTTP-204

• HTTP-200

• HTTP-202

Но нужно понимать, что у каждого из них есть свой технический смысл.

Trello и Todoist соответствуют рекомендациям по дизайну RESTful API.

8. Может ли быть у DELETE тело запроса?

Согласно рекомендациям по REST API, которые опубликованы в Mozilla:

Метод DELETE не предполагает определённого смысла для тела запроса, поэтому оно должно быть пустым, как и в GET.

В Trello метод удаления карточки DELETE /cards/{cardId} тело пустое.

В Todoist метод удаления задачи DELETE /tasks/{taskId} тело пустое.

При большом желании как в GET, так и в DELETE можно передавать тело запроса, но на уровне протокола HTTP и рекомендаций REST API они не ожидаются.

Итого:
Trello и Todoist соответствуют рекомендациям по дизайну RESTful API.

9. Чем отличается REST от RESTful API?

В самом начале статьи есть ответ на этот вопрос:

• Если API на все 100% соответствует архитектурному стилю REST, то его обычно называют RESTful API.

• Если API в основном соответствует архитектурному стилю REST, но часть принципов нарушена, то его обычно называют REST API.

По итогам исследований большая часть рекомендаций, которые были разобраны в этой статье, соблюдена как Trello, так и Todoist.

Но если говорить о том, какой API больше RESTful, то однозначно Trello.

Почему я не считаю, что Todoist соблюдает принципы RESTful API? Всё из-за метода POST на редактирование данных, где ожидалось увидеть PATCH или PUT.

Заключение

В этой статье я поделилась с вами исследованиями реальных REST API, на примере которых можно отстаивать свою правоту на собеседованиях и для команды при проектировании.

Она же может стать вашим помощником при работе на проектах и принятии важных решений по созданию новых методов, так как в ней есть подборки стандартов отрасли и разных API по обозначенным в начале вопросам.

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

Все рекомендации по проектированию методов REST API давала в этой статье: Проектирование REST API: спорные вопросы с проектов и собеседований на системного аналитика (и не только).

Что еще почитать и посмотреть по REST API

Хорошо подойдет для тех, кто только пытается разобраться что это и зачем.

YouTube:

• Связь базы данных и дизайн REST API.

• Postman - навык тестирования REST API за вечер.

• REST API с нуля - дизайн методов для работы с заявками автосервиса.

База знаний GetAnalyst:

• Подкаст "Вопросы и ответы по REST API: собеседование на системного аналитика"

• Статья "Простыми словами про API"

• Подкаст "Авторизация в API: что нужно знать системным аналитикам для работы с требованиями и собеседований"

• Шаблон постановки задачи на REST API метод

Книги:

• "Проектирование веб-API", Арно Лоре.

• "CHAPTER 5. Representational State Transfer (REST)" - диссертация Роя Филдинга (англ).

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