Рекомендуемая маска:
<Вид метода HTTP>
<Протокол>
://
<Доменное имя>
/ api
/ <имя API> /
<версия>
/ <путь: названия сущностей и path-параметры> ?
<query-параметры>
✅ Метод HTTP
Не относится к URL, но тесно связан с ним. Правила выбора в этом посте.
✅ Протокол
В начале любого URL указывается протокол HTTP(s).
✅ Доменное имя
Основной адрес, по которому можно обращаться к серверу.
✅ Путь (Path)
Включает в себя один или несколько сегментов, разделённых слешами (/):
▫️“api” - указатель на каталог API сервера, может быть название вида api.
▫️имя API - указывает на конкретный интерфейс API, предназначенный для разных пользователей системы.
▫️v1 - версия API, важна для поддержки совместимости с предыдущими версиями.
В этой части может быть организована иерархия связанная с вложенными сущностями или действиями над объектами:
▫️recipes - это ресурс, к которому осуществляется доступ. В данном случае “рейепт”. Может быть в единственном числе (recipe).
▫️{recipeId} - это параметр в пути URL (path-параметр), указывающий на конкретный рецепт по его id в БД системы. Фигурные скобки {} обозначают переменную часть URL, значение которой должно быть предоставлено клиентом (например, идентификатор 18290).
✅ Query-параметры (Query-parameters)
Дополнительные параметры запроса после ?, необязательны. Если их несколько, то перечисление через символ &.
Обычно используются для фильтров, сортировок и пагинации при получении списков методом GET, но могут быть и в других методах.
В примере:
GET …/recipes?offset=0&limit=20&name=пирог&authorId=777
👉 ?offset=0&limit=20 - запрос результатов с 0-го, ограниченный 20-ю на страницу. Это два отдельных query-параметра - элементы пагинации (постраничного получения данных).
👉 name и authorId - фильтры по названию и id автора рецепта.
Больше примеров на картинках 🖼
Благодаря такой структуре всегда понятно, каким ресурсом (сущностью) управляет REST API метод ✅
#RestApiGA #RecipeGA