Проектування URL RESTful API: Посібник з Endpoint для розробників

Найкращі практики для проектування endpoint RESTful API. Створюйте чисті, послідовні та масштабовані структури URL API.

У проектуванні RESTful API структура URL безпосередньо впливає на зручність використання та підтримку вашого API. У цьому посібнику ми навчимося проектувати дружні до розробників endpoint API.

Основи REST

Що таке REST?

Representational State Transfer (REST) — це архітектурний стиль для веб-API. Він представляє ресурси через URL та використовує HTTP методи.

HTTP методи

GET    → Читання ресурсу
POST   → Створення нового ресурсу
PUT    → Повна заміна ресурсу
PATCH  → Часткове оновлення ресурсу
DELETE → Видалення ресурсу

Принципи проектування URL

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

# НЕПРАВИЛЬНО - Використання дієслів
GET  /getUsers
POST /createUser

# ПРАВИЛЬНО - Використання іменників
GET    /users
POST   /users

2. Використовуйте множину

# НЕПРАВИЛЬНО
/user
/product

# ПРАВИЛЬНО
/users
/products

3. Ієрархічна структура

# Замовлення користувача
GET /users/123/orders

# Товари замовлення
GET /orders/456/items

Версіонування

Версія в URL

# Найпоширеніший метод
https://api.example.com/v1/users
https://api.example.com/v2/users

Фільтрація, сортування та пагінація

Фільтрація

# Проста фільтрація
GET /products?category=electronics

# Оператори порівняння
GET /products?price[gte]=100&price[lte]=500

Сортування

# Сортування за одним полем
GET /products?sort=price
GET /products?sort=-price        # Спадання

Пагінація

# На основі offset
GET /products?page=2&per_page=20

# На основі курсора (більш продуктивна)
GET /products?cursor=abc123&limit=20

HTTP коди стану

# Успіх
200 OK           → GET, PUT, PATCH успішний
201 Created      → POST успішний
204 No Content   → DELETE успішний

# Помилки клієнта
400 Bad Request  → Недійсний запит
401 Unauthorized → Потрібна автентифікація
403 Forbidden    → Немає дозволу
404 Not Found    → Ресурс не знайдено

Висновок

Добре спроектовані URL API підвищують зручність використання вашого API та полегшують підтримку. Створюйте дружні до розробників API, використовуючи послідовне іменування, логічну ієрархію та стандартні HTTP методи.