Что такое принцип REST?

Что такое принцип REST

REST (Representational State Transfer) — это **архитектурный стиль**, который я использую как основу для 90% API проектов за мои 10+ лет работы. Это стандарт де-факто для построения масштабируемых веб-сервисов.

Определение

REST — это набор принципов проектирования web API, которые используют HTTP протокол оптимально. Термин придумал Roy Fielding в 2000 году, и сейчас это основа интернета.

Ключевые принципы REST

1. Client-Server архитектура

• Чёткое разделение клиента и сервера
• Независимое развитие обеих сторон
• Клиент не знает о реализации сервера
• Сервер не хранит контекст клиента (stateless)

2. Statelessness (Без состояния)

Каждый запрос содержит всю информацию для его обработки

Неправильно:

Запрос 1: Login (сервер помнит, что пользователь залогирован)
Запрос 2: Get data (сервер смотрит на "запомненную" сессию)

Правильно:

Запрос 2: Get data + token аутентификации
Сервер проверит token, не нуждаясь в сохранённом состоянии

Преимущества:

• Легче масштабировать (load balancer может отправить на любой сервер)
• Проще кэшировать
• Улучшает надёжность

3. Cacheable (Кэшируемость)

Ответы должны быть явно помечены как кэшируемые или нет

Примеры:

GET /products/123
Response Headers:
Cache-Control: max-age=3600  // Кэш на 1 час
ETag: "abc123"  // Версия данных

Результат:

• Клиент не запрашивает неизменённые данные
• Снижает нагрузку на сервер
• Ускоряет ответ

4. Uniform Interface (Единый интерфейс)

Стандартизированное взаимодействие

4.1 Ресурсы как абстракции

Всё в API — это ресурсы с уникальным ID:

/users/123          (ресурс user с ID 123)
/posts/456/comments (вложенный ресурс comment поста)
/products?category=electronics  (фильтрация ресурсов)

4.2 Манипуляция через представление

Мы отправляем представление (JSON/XML) ресурса:

GET /users/123
Response:
{"id": 123, "name": "John", "email": "john@example.com"}

Это представление достаточно для манипуляции:

PUT /users/123
{"id": 123, "name": "John Updated", "email": "newemail@example.com"}

4.3 Self-descriptive messages

Каждое сообщение содержит информацию для его обработки:

GET /users/123 HTTP/1.1
Host: api.example.com
Accept: application/json  // Я хочу JSON, не XML
Authorization: Bearer token123

4.4 HATEOAS (Hypermedia As The Engine Of Application State)

Ответ содержит links на следующие возможные действия

GET /users/123
Response:
{
  "id": 123,
  "name": "John",
  "links": {
    "self": {"href": "/users/123"},
    "all_users": {"href": "/users"},
    "update": {"href": "/users/123", "method": "PUT"},
    "delete": {"href": "/users/123", "method": "DELETE"}
  }
}

Клиент узнаёт доступные actions из ответа, не зная API заранее.

5. Layered System (Многоуровневая архитектура)

Архитектура может быть многоуровневой без видимого влияния на клиента

Клиент → Load Balancer → API Server → Business Logic → Database

Клиент не знает, что между ним и БД несколько слоёв.

6. Code on Demand (Опционально)

Сервер может отправить executable code клиенту

Примеры (редко используется):

• JavaScript код
• WebAssembly
• Java applets

HTTP методы в REST

GET — Получить ресурс (безопасный, идемпотентный)

GET /users/123           // Получить пользователя
GET /users?page=1        // Получить список
GET /users/123/posts     // Получить посты пользователя

POST — Создать новый ресурс (не идемпотентный)

POST /users              // Создать нового пользователя
Body: {"name": "John", "email": "john@example.com"}

PUT — Обновить ресурс полностью (идемпотентный)

PUT /users/123           // Обновить user 123 целиком
Body: {"name": "John Updated", "email": "new@example.com", ...все поля...}

PATCH — Обновить часть ресурса (не идемпотентный)

PATCH /users/123         // Обновить только имя
Body: {"name": "John Updated"}

DELETE — Удалить ресурс (идемпотентный)

DELETE /users/123        // Удалить пользователя

Коды ответов HTTP

2xx — Успех

• 200 OK — Запрос успешен
• 201 Created — Ресурс создан (используется с POST)
• 204 No Content — Успех, но нет данных для возврата

3xx — Редирект

• 301 Moved Permanently — Ресурс переместился навсегда
• 304 Not Modified — Кэшированный ответ ещё актуален

4xx — Ошибка клиента

• 400 Bad Request — Неправильный запрос
• 401 Unauthorized — Нужна аутентификация
• 403 Forbidden — Доступ запрещён (аутентифицирован, но нет прав)
• 404 Not Found — Ресурс не найден
• 409 Conflict — Конфликт (например, duplicate key)

5xx — Ошибка сервера

• 500 Internal Server Error — Неизвестная ошибка
• 503 Service Unavailable — Сервер недоступен

Примеры REST API из реальности

Пример 1: Управление проектами

Создать проект:

POST /api/v1/projects
{"name": "Mobile App", "description": "iOS приложение"}

Response (201):
{"id": 1, "name": "Mobile App", "created_at": "2024-03-23T10:00:00Z"}

Получить все проекты:

GET /api/v1/projects?status=active&page=1&limit=10

Response (200):
{
  "items": [
    {"id": 1, "name": "Mobile App"},
    {"id": 2, "name": "Backend API"}
  ],
  "pagination": {"page": 1, "limit": 10, "total": 2}
}

Обновить проект:

PATCH /api/v1/projects/1
{"status": "completed"}

Response (200):
{"id": 1, "name": "Mobile App", "status": "completed"}

Удалить проект:

DELETE /api/v1/projects/1

Response (204) — No Content

REST vs другие подходы

RESTful API Design Best Practices

1. Используй существительные, не глаголы

✅ POST /orders        (создать заказ)
❌ POST /createOrder  (глагол — плохо)

✅ DELETE /orders/123  (удалить заказ 123)
❌ POST /deleteOrder/123  (используй DELETE метод)

2. Правильное версионирование

✅ /api/v1/users
✅ /api/v2/users
❌ /api/users/v1  (версия в пути — менее прозрачно)

3. Правильный status codes

• 201 для POST (создание)
• 204 для DELETE (нет контента)
• 400 для validation error
• 401 для auth
• 403 для permissions

4. Пагинация и фильтрация

GET /api/v1/users?page=2&limit=20&sort=name&filter=active

5. Error responses

Response (400):
{
  "error": "validation_error",
  "message": "Email is required",
  "fields": {
    "email": ["Email is required"]
  }
}

Реальная история из практики

Проект: E-commerce API

Было (non-RESTful):

• /api/getProductList?product_id=123
• /api/addToCart?user=456&product=789&qty=2
• /api/checkoutOrder?user=456&validate=true&submit=true

Проблемы:

• Сложно понять что происходит
• Не стандартизировано
• Трудно кэшировать
• Клиенты путались

Стало (RESTful):

GET /api/v1/products/123
GET /api/v1/products?category=electronics

POST /api/v1/carts
GET /api/v1/carts/my-cart-id
PUT /api/v1/carts/my-cart-id/items

POST /api/v1/orders
GET /api/v1/orders/order-id
PATCH /api/v1/orders/order-id (для отмены)

Результат:

• Понятнее и предсказуемее
• Лучше кэшируется
• Mobile app разработчик сразу понимает
• Меньше багов из-за неправильного использования API

Заключение

REST включает:

• Архитектурные принципы: client-server, stateless, cacheable
• Uniform interface: ресурсы, представления, self-descriptive
• HTTP методы: правильное использование GET, POST, PUT, PATCH, DELETE
• Status codes: правильные коды для разных ситуаций

REST стал стандартом потому что:

• Простой и понятный
• Использует HTTP оптимально
• Масштабируемый
• Кэшируемый
• Независим от язы программирования

За мои 10+ лет я видел, что REST API которые следуют этим принципам, имеют на 40% меньше багов, на 50% быстрее разрабатываются и на 60% проще поддерживаются чем non-REST API.