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

При написанні API потрібно давати правильні назви ресурсам. Адже інтуїтивні та прості найменування спрощують використання сервісу.

Кінцеві URL за запитом ресурсу також називають endpoints API.

Хороший підхід вибору найменування:

• Для опису базових URL використовують іменники у множині - users, contacts.

• Використовують конкретні та чіткі імена - на кшталт news, videos, а не абстрактні items або elements.

• Складну логіку URL описують додаванням властивостей. Параметри ховають за знаком питання ?. Наприклад як при організації пагінації: /news?limit=25&offset=50

Розглянемо приклади хороших практик найменування:

Створити дані про клієнта:

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