От того, как вы выбираете метод + URL, зависит, будет ли ваш REST API понятным и предсказуемым для клиентов и команды.
В этом посте разберём типовые ошибки в дизайне эндпоинтов — те самые, из-за которых потом появляются “костыли”, споры в чатах и переделки.
API-метод:
👉 Получение списка вакансий
[результаты]
❌ A. POST .../api/v1.1/jobs/search
Получение, просмотр, поиск - это всё про метод GET.
Метод POST - для создания данных в БД.
Да, так делают. Но это уже просто HTTP API, без стиля REST.
❌ B. GET .../api/jobs/v1.1/list
Две ошибки в одном методе и 14% голосов 🥲
1. Версию рекомендуется делать ДО указания ресурса / объекта данных (jobs), которым управляют.
2. Никакого list не надо! По стандарту GET /jobs/{jobId} получить конкретную вакансию, а GET /jobs без id - список.
✅ C. GET .../api/v1.1/jobs
Тут всё идеально с точки зрения дизайна REST API.
❌ D. POST .../api/v1.1/jobs
Метод POST - для создания данных в БД.
Это метод "Создать вакансию".
✅ E. GET .../api/v1.1/job
Тут всё отлично, но голосов мало.
Почему не выбрали?
👉 Единственное число в эндпоинте - это ок для REST API. Писала об этом тут.
▫️ F. GET .../api/v1.1/public/jobs
Ок, но не ок.
Если public - название каталога API на сервере, то лучше его делать ДО версии, а не после.
Вариант допустим, но не лучший.
▫️ G. GET .../api/v1.1/candidate/jobs
Ок, но не ок.
Проблема как и выше, но тут считаем, что API для кандидата и название каталога API - candidate?
Сейчас метод читается как "получить вакансии кандидатов...?".
❌ H. GET https://jobmatchga.api.com/v1.1/jobs
Здесь с точки зрения порядка в базовом URL api.com оказывается основным сайтом системы, что неверно.
Поддомен для API делают иначе.
✅ I. GET https://api.jobmatchga.com/public/
v1.1/jobs
Тут всё отлично.
API находится на поддомене основного сайта jobmatchga.com.
Дизайн отличный и почему-то так мало голосов 😃
Пример в Avito
—-
Подсказки:
📚 Как выбирать методы: GET, POST, PUT, PATCH, DELETE
📚 Правила проектирования URL
—-
Запоминайте ошибки и будьте внимательны в будущем. Не попадайтесь! 🤝
#RestApiGA #JobMatchGA