💜 10 элементов URL в REST API: чек-лист с примерами 💜

Пример - редактировать карточку питомца:
PUT https://vetcare.com/api/public/v1/pets/{petId}

1️⃣ Метод HTTP
GET, POST, PUT, PATCH, DELETE
Не относится к URL, но связан с ним, т.к. вместе образуют эндпоинт.
Подробнее тут

2️⃣ Протокол
Для REST API всегда HTTP / HTTPs

3️⃣ Доменное имя
Основной адрес, по которому можно обращаться к серверу с API-приложением (backend)

Путь (Path)
Включает в себя один или несколько сегментов, разделённых слешами (/):
4️⃣ api - указатель на каталог API сервера, может быть в доменном имени
5️⃣ имя API (public) - указывает на конкретный интерфейс API, предназначенный для разных пользователей системы, либо для разных микросервисов
6️⃣ v1 - версия API, важна для поддержки совместимости с предыдущими версиями

Эндпоинт:
7️⃣ pets - это ресурс, к которому осуществляется доступ. В данном случае “питомец”. Может быть в единственном числе (pet)
8️⃣ {petId} - это параметр в пути URL (path-параметр), указывающий на конкретного питомца по его id в БД системы. Фигурные скобки {} обозначают переменную часть URL, значение которой должно быть предоставлено (например, идентификатор 126734)

+ 9️⃣ Иерархия с вложенными сущностями/действия над объектами
Примеры:
GET ../orders/(id}/payments - получить платеж(и) по заказу
PATCH ../users/(id}/block - заблокировать пользователя


+ 🔟 Query-параметры
Это дополнительные параметры после ?.
Они не являются обязательной частью URL.
Если параметров несколько, они перечисляются через символ &.
Обычно query-параметры используют для фильтрации, сортировки и пагинации при получении списков методом GET, но могут быть и в других методах.

Пример - список ветеринаров:
GET …/vets?offset=0&limit=10&name=Иванов
👉 offset=0&limit=10 - запрос результатов с 0-го, 10 элементов на страницу. Это два отдельных query-параметра - элементы пагинации (постраничного получения данных)
👉 name - фильтр по имени ветеринара



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


К посту прикрепилb наглядный практический гайд с дополнительными примерами — забирайте себе как шпаргалку для работы и собеседований 📚🔖

#hardGetAnalyst