Пример:
PATCH https://farmfresh.com/api/catalog/v1/products/{productId}
1️⃣ Метод HTTP
GET, POST, PUT, PATCH, DELETE
Не относится к URL, но связан с ним.
Подробнее тут
2️⃣ Протокол
Для REST API всегда HTTP / HTTPs
3️⃣ Доменное имя
Основной адрес, по которому можно обращаться к серверу с API-приложением (backend)
Путь (Path)
Включает в себя один или несколько сегментов, разделённых слешами (/):
4️⃣ api - указатель на каталог API сервера, может быть в доменном имени
5️⃣ имя API - указывает на конкретный интерфейс API, предназначенный для разных пользователей системы, либо для разных микросервисов
6️⃣ v1 - версия API, важна для поддержки совместимости с предыдущими версиями
Эндпонит:
7️⃣ products - это ресурс, к которому осуществляется доступ. В данном случае “продукт”. Может быть в единственном числе (event)
8️⃣ {productId} - это параметр в пути URL (path-параметр), указывающий на конкретный продукт по его id в БД системы. Фигурные скобки {} обозначают переменную часть URL, значение которой должно быть предоставлено (например, идентификатор 2324)
9️⃣ иерархия с вложенными сущностями/действия над объектами.
Примеры:
GET ../orsers/(id}/payments - получить платеж(и) по заказу
PATCH ../users/(id}/block - заблокировать пользователя
9️⃣ Query-параметры
Дополнительные параметры после ?, необязательны.
Если их несколько, то перечисление через символ &.
Обычно используются для фильтров, сортировок и пагинации при получении списков методом GET, но могут быть и в других.
Пример:
GET …/products?offset=0&limit=10&name=брокколи
👉 offset=0&limit=10 - запрос результатов с 0-го, 10 элементов на страницу. Это два отдельных query-параметра - элементы пагинации (постраничного получения данных)
👉 name - фильтр по названию продукта
➕ Есть исключения из правил, особенности и ошибки. Часть разобрала на картинках к посту - ответы квиза.
Благодаря такой структуре разработчикам и пользователям API всегда понятно, что ожидать от REST API метода 🙌
#RestApiGA #FarmFreshGA