Як правильно верстати URI і працювати з ресурсами

URI (Uniform Resource Identifier) є ключовим інтерфейсом між вашим API і його користувачами. Уявіть, що URI — це адреси на карті, які користувачі (маючи в руках навігатор) будуть використовувати для доступу до функцій вашого додатка. Якщо ваш URI буде заплутаним, несузгодженим і недоробленим, користувачі API відчуватимуть той самий дискомфорт, що й ми, коли їдемо через усе місто, щоб дізнатися, що адреса веде в нікуди.

Чітко спроектовані URI:

• Покращують читабельність і передбачуваність API.
• Забезпечують одноманітність і спрощують підтримку.
• Допомагають новому розробнику швидше зрозуміти структуру API.
• Сприяють масштабованості системи в майбутньому.

Основні правила створення URI

Ми вже з цим розбиралися, але варто повторити. Тож запам'ятайте, як мантру: "URI мають бути інтуїтивно зрозумілими і описувати ресурс, а не дію". Ось що це означає:

1. Використовуйте іменники замість дієслів

URI повинні представляти ресурс, а не дію над ним. Наприклад:

• Правильно: /users (описує ресурс "користувачі").
• Неправильно: /getAllUsers (описує дію).

Приклад:

GET /users       -> Отримати список усіх користувачів.
GET /users/{id}  -> Отримати дані конкретного користувача.
POST /users      -> Створити нового користувача.

Такий підхід робить API передбачуваним. Ймовірність того, що розробник промахнеться і введе неправильний URI, значно знижується.

2. Використовуйте множину для колекцій

Коли ви розробляєте маршрути для колекцій, таких як список користувачів або список продуктів, використовуйте множину. Це загальноприйнята угода в REST API.

Приклад:

/products        -> Список усіх продуктів.
/products/{id}   -> Конкретний продукт за ID.

Чому це важливо? Тому що так одразу зрозуміло, що /products — це група, а /products/{id} — конкретний представник цієї групи.

3. Використовуйте вкладення для логічної ієрархії

Якщо ваші ресурси мають залежність або вкладеність, це можна виразити через структуру URI. Наприклад, замовлення користувача можна представляти так:

GET /users/{userId}/orders       -> Отримати всі замовлення користувача.
/users/{userId}/orders/{orderId} -> Отримати конкретне замовлення для користувача.

Вкладена структура URI допомагає показати зв'язок між двома ресурсами. Наприклад, "замовлення" без користувача може бути незрозумілим, але всередині /users/{userId} воно відразу набуває сенсу.

4. Консистентність і читабельність

Часто в проєктах зустрічаються URI на кшталт цього:

/api/v1/get_all_users

Ну таке... Тут порушено все:

• Використання підкреслення замість дефіса.
• Вказані дії замість ресурсів (get_all_users).
• Дотримання неявних домовленостей щодо написання.

Добре оформлений URI:

/api/v1/users

• Дефіси для поділу слів (-), а не підкреслення (_).
• Мінімалізм: пишемо тільки те, що важливо.

Дефіси в URI краще сприймаються і вважаються більш читабельними.

Робота з версіями API

Версіонування — важливий аспект гнучкого API. Воно дозволяє вашому API еволюціонувати без ламання старих клієнтів. Зазвичай версії включаються в URI.

Способи версіонування:

1. Версія в шляху:

   
   /api/v1/users
   

   Простий, стандартний підхід. Зручно для REST API.
2. Версія в заголовку: Вказуєте версію через HTTP-заголовок:

   
   GET /users
   Content-Type: application/json
   API-Version: 1
   

3. Версія в параметрі запиту:

   
   /users?apiVersion=1
   

Для простоти ми частіше будемо використовувати версію в шляху.

Вкладеність і структурованість

Вкладені URI використовуються для представлення зв'язків між ресурсами. Але важливо пам'ятати, що надмірна вкладеність ускладнює підтримку. Вкладеність більше трьох рівнів вже вважається ознакою поганої архітектури.

Хороший приклад:

/users/{userId}/orders/{orderId}

Поганий приклад:

/companies/{companyId}/departments/{departmentId}/teams/{teamId}/users/{userId}

Якщо у вас з'являється така глибока структура, можливо, варто переглянути модель даних. Наприклад, додати окремий сервіс для керування "користувачами".

Де використовувати Query Parameters?

Query Parameters (параметри запиту) зручні, якщо ви хочете відфільтрувати, відсортувати або уточнити дані. Наприклад:

GET /products?category=electronics&sort=price_asc&page=2

Розподіл обов'язків:

1. URI використовують для ідентифікації ресурсів.
2. Query Parameters — для пошуку, сортування або обмеження.

Приклад: впроваджуємо на практиці

Давайте застосуємо все, чому навчилися, і створимо REST API для роботи з ресурсами "Користувачі" і "Замовлення".

REST-контролер для користувачів

@RestController
@RequestMapping("/api/v1/users")
public class UserController {

    // Отримати всіх користувачів
    @GetMapping
    public List<User> getAllUsers() {
        return userService.getAllUsers();
    }

    // Отримати одного користувача
    @GetMapping("/{userId}")
    public User getUserById(@PathVariable Long userId) {
        return userService.getUserById(userId);
    }

    // Створити користувача
    @PostMapping
    public User createUser(@RequestBody User newUser) {
        return userService.createUser(newUser);
    }

    // Оновити користувача
    @PutMapping("/{userId}")
    public User updateUser(@PathVariable Long userId, @RequestBody User updatedUser) {
        return userService.updateUser(userId, updatedUser);
    }

    // Видалити користувача
    @DeleteMapping("/{userId}")
    public void deleteUser(@PathVariable Long userId) {
        userService.deleteUser(userId);
    }
}

Обробка вкладеності для замовлень

@RestController
@RequestMapping("/api/v1/users/{userId}/orders")
public class OrderController {

    // Отримати всі замовлення користувача
    @GetMapping
    public List<Order> getAllOrdersForUser(@PathVariable Long userId) {
        return orderService.getOrdersByUserId(userId);
    }

    // Отримати конкретне замовлення
    @GetMapping("/{orderId}")
    public Order getOrderById(@PathVariable Long userId, @PathVariable Long orderId) {
        return orderService.getOrderById(userId, orderId);
    }

    // Створити замовлення
    @PostMapping
    public Order createOrder(@PathVariable Long userId, @RequestBody Order newOrder) {
        return orderService.createOrderForUser(userId, newOrder);
    }
}

Приклад запитів:

1. Отримати всіх користувачів:

   
   GET /api/v1/users
   

2. Створити нового користувача:

   
   POST /api/v1/users
   {
       "name": "John Doe",
       "email": "john.doe@example.com"
   }
   

3. Отримати всі замовлення користувача:

   
   GET /api/v1/users/1/orders
   

4. Додати замовлення користувачу:

   
   POST /api/v1/users/1/orders
   {
       "product": "Laptop",
       "quantity": 1
   }
   

Тепер у вашому REST API панує порядок і краса. Продуманий дизайн URI — запорука зручності й довговічності вашого API!