🐞 Разбор квиза по REST API - ошибки, которые допускают из-за отсутствия насмотренности и опыта 🐞

Пару дней назад я опубликовала вопросы с подвохами по REST API.

✅ Результаты тут

Как всегда, вижу сильный перекос голосов в сторону:
«а давайте всё сделаем через POST» 🙃

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

Если это HTTP API без REST-подхода, то может получиться так:

POST /api/public/v1/appointments/create - создать запись

POST /api/public/v1/appointments/{id} - получить запись по id

POST /api/public/v1/appointments/list - получить список записей

POST /api/public/v1/appointments/{id}/update - редактировать запись (отменить)

POST /api/public/v1/appointment/{id}/delete - удалить запись

Почему это не REST?
❌ В URL используются глаголы, хотя их роль уже могут выполнять HTTP-методы: GET, POST, PUT, PATCH, DELETE.



Если делаете REST API, то запись того же CRUD будет выглядеть так:

POST /api/public/v1/appointments - создать запись

GET /api/public/v1/appointments/{id} - получить запись по id

GET /api/public/v1/appointments - получить список записей, не конкретная по id

PATCH /api/public/v1/appointments/{id} - редактировать запись (отменить)

DELETE /api/public/v1/appointments/{id} - удалить запись

Почему это ближе к REST?
✅ В URL нет лишних глаголов.
✅ Действие определяется HTTP-методом.
✅ URL описывает ресурс, а не команду.


*public — это название API. Его можно опустить, но на практике часто полезно сохранять, особенно в микросервисной архитектуре.


❗️Главное правило перед проектированием эндпоинтов RESTful API:
сначала распишите полный набор операций для одного ресурса по CRUD и проверьте, чтобы не было конструкций вроде: POST /objects/create.
Потому что здесь уже возникает дублирование смысла: POST = create, а create ещё раз написан в URL.

Это минимальное, чтобы уйти от HTTP API в сторону REST-а.

Итого, ключевые ошибки в тестировании:

👉 1. Запись на приём
Большинство выбрали верный вариант.
Но много голосов было и за:
❌ POST /appointments/create - это "масло-маслянное"
❌ POST /appointments/{id} - откуда возьмете id? он же присваивается после создания записи на сервере, в БД


👉 2. История записей
По сути это обычное получение списка записей на приём.
Большинство выбрали корректные варианты, но здесь важно помнить ещё одну вещь:
❗️В идеале нужно было в предложенных решениях добавить названия API:

/api/admin/v1
/api/public/v1

А я их благополучно скрыла от вас.


👉 3. Отмена записи
За DELETE - большинство голосов.
Но отмена записи — это чаще не удаление строки из БД, а изменение статуса.
Поэтому более точный вариант здесь — PATCH, если мы, например, меняем статус записи на cancelled.
DELETE иногда тоже встречается, но с точки зрения бизнес-смысла PATCH здесь обычно аккуратнее.


📌 Почему "все POST" это не REST?
“всё через POST” не доказывает автоматически, что API не REST,
но очень часто означает, что API игнорирует стандартную семантику HTTP и уходит в сторону RPC over HTTP — этот вывод следует из сочетания RFC 9110 и диссертации Филдинга
▫️ HTTP требует уважать семантику методов — RFC 9110
▫️ REST определяется наличием uniform interface и hypermedia constraints — Филдинг, 5.1.5 - “REST APIs must be hypertext-driven”.



Подробный разбор каждого варианта — на картинках к посту 🤝
🖼 Исходники картинок


Полезные материалы, связанные с решением:
📚 Шпаргалка по методам: GET, POST, PUT, PATCH, DELETE
📚 Примеры API с разбором структуры методов
📚 Структура URL в REST API
🩵 Проектирование REST API: спорные вопросы с проектов и собеседований на системного аналитика (и не только)

Пример HTTP API:
https://www.unisender.com/ru/support/api/common/bulk-email/
Пример REST API:
https://developers.avito.ru/api-catalog/job/documentation#operation/applicationsGetIds



#RestApiGA #VetCareGA (Tg | ВК | Max)