Пару дней назад я опубликовала вопросы с подвохами по 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)