Формування URL для REST API

У цьому розділі ми поговоримо про правильне найменування ресурсів для API. Коли ресурси названі правильно, API інтуїтивно зрозумілий та простий у використанні. Часто кінцеві URL за запитом ресурсу називають endpoints API

Що є хорошою практикою для правильного іменування?

Ну по перше необхідно використовувати для опису базових URL іменники у множині - users, contacts. Також треба використовувати більше конкретні та чіткі імена news, videos, а не абстрактні items або elements. Складну логіку для URL необхідно описувати за рахунок додаткових властивостей, тобто, ховати за знаком ?. Приклад використання пагінації /users?limit=25&offset=50, фільтрація відповіді /friends?fields=id,name,picture

Виходячи зі сказаного наступні назви будуть поганою практикою

/api/users/13/remove
/api/getusers
/api/v1/users-get

Тут ми використовуємо дієслова, вказуємо видалення для /api/users/13/remove, а необхідно просто використовувати HTTP метод DELETE

Давайте розглянемо хороші практики іменування URL для різноманітних ситуацій

Додавання нового клієнта до системи:

HTTP метод: POST
URL: http://www.example.com/customers

Отримати дані клієнта з ідентифікатором клієнта ID 112233:

HTTP метод: GET
URL: http://www.example.com/customers/112233

Той самий URL ми використовуємо для HTTP методів PUT та DELETE для оновлення та видалення відповідно.

Створення нового продукту:

HTTP метод: POST
URL: http://www.example.com/products

Для читання, оновлення, видалення продукту з ID 432111, відповідно:

HTTP метод: GET, PUT, DELETE
URL: http://www.example.com/products/432111

Створення нового замовлення для клієнта поза контекстом клієнта

HTTP метод: POST
URL: http://www.example.com/orders

Створення того ж замовлення, але в контексті конкретного клієнта з ID 332244

HTTP метод: POST
URL: http://www.example.com/customers/332244/orders

Список замовлень, що належать клієнту ID 332244:

HTTP метод: GET
URL: http://www.example.com/customers/332244/orders

Нехай необхідний URL для додавання нової позиції на замовлення з ID 1234, для клієнта з ID 332244:

HTTP метод: POST
URL: http://www.example.com/customers/332244/orders/1234/lineorders

Отримання списку замовлення за ID замовлення без знання ID конкретного клиента

HTTP метод: GET
URL: http://www.example.com/orders/8769

Пагінація проводиться через query рядок за допомогою параметра offset - це початковий номер позиції, та параметр limit - максимальна кількість елементів, що повертаються. Вони можуть називатися і інакше, наприклад skip, limit

HTTP метод: GET
URL: http://api.example.com/resources?offset=0&limit=25

Складна фільтрація за значеннями. Можна використовувати роздільник подвійна двокрапка ::, яке відокремлює ім'я властивості від значення порівняння

HTTP метод: GET
URL: http://www.example.com/users?filter="name::sam|city::denver"

Сортування. Один із способів, коли для кожної переданої властивості проводиться сортування в порядку зростання, а для кожної властивості, з префіксним тире ("-") сортування проводиться у порядку зменшення. Сепаратор для кожного імені властивості вертикальна смуга ("|")

HTTP метод: GET
URL: http://www.example.com/users?sort=lastName|firstName|-birthdate

Сподіваюся з цих прикладів вам стало відомо, як потрібно називати ресурси для вашого API