В чем принципы REST API

[saltvsvinegar]

Можешь рассказать все принципы REST API?

 

[ChatGPT]

REST — это не “формат API”, а набор архитектурных принципов, как строить взаимодействие клиент↔сервер поверх HTTP так, чтобы было просто масштабировать, кешировать и развивать без боли. Классические принципы (ограничения) REST по Рою Филдингу — вот они.

## 1) Client–Server (клиент–сервер)
Клиент и сервер разделены по ответственности:

• клиент отвечает за UI/UX и то, как показывать данные;
• сервер отвечает за данные и бизнес-логику.

Плюс: можно независимо развивать фронт и бэк, менять технологии, не ломая всё.

## 2) Stateless (отсутствие состояния на сервере)
Каждый запрос самодостаточен: сервер не хранит “сессию” клиента между запросами (в идеале).

• всё нужное для обработки запроса должно быть в нём: токен/ключ, параметры, тело, заголовки.
• если нужна авторизация — обычно через Authorization: Bearer <token> (JWT/opaque token), а не “сессия в памяти”.

Плюс: горизонтальное масштабирование сильно проще (любой инстанс обработает любой запрос).

## 3) Cacheable (кешируемость)
Ответы должны явно говорить, можно ли их кешировать и как:

• HTTP-заголовки: Cache-Control, ETag, Last-Modified, Expires.
• клиент/прокси могут повторно использовать ответы, снижая нагрузку.

Пример: ETag + If-None-Match → сервер может вернуть 304 Not Modified.

## 4) Uniform Interface (единый интерфейс)
Самая “rest-овая” часть. Идея: общие правила взаимодействия для всех ресурсов.

Обычно её раскладывают на 4 подпункта:

### 4.1) Identification of resources (идентификация ресурсов)
Ресурсы адресуются URI:

• /users/42
• /orders/2025-001/items

Ресурс — это “сущность/коллекция”, а не “метод”.
Поэтому вместо /getUser?id=42 — /users/42.

### 4.2) Manipulation through representations (манипуляция через представления)
Клиент работает не с “объектом в базе”, а с представлением ресурса:
- JSON, XML, HTML, etc.
Клиент отправляет представление → сервер применяет изменения.

### 4.3) Self-descriptive messages (самоописываемые сообщения)
Сообщение должно нести достаточно мета-информации:

• Content-Type: application/json
• коды статуса (200, 201, 400, 404, 409, 422, 500…)
• ссылки/поля, поясняющие, что это за данные (в идеале).

### 4.4) HATEOAS (Hypermedia as the Engine of Application State)
Самый редко реализуемый пункт “по канону”.
Суть: сервер возвращает не только данные, но и ссылки/действия, доступные дальше.

Пример (упрощённо):

{
  "id": 42,
  "status": "created",
  "links": {
    "self": "/orders/42",
    "pay": "/orders/42/pay",
    "cancel": "/orders/42/cancel"
  }
}

Идея: клиент меньше “хардкодит” маршруты и бизнес-переходы.

## 5) Layered System (слоистая система)
Клиенту всё равно, общается ли он напрямую с сервером или через слои:
- CDN, reverse proxy, API gateway, балансировщик, кэш, сервисы.

Плюс: масштабирование, безопасность, наблюдаемость (rate limit, auth, логирование) проще.

## 6) Code on Demand (код по требованию) — опционально
Сервер может отдавать исполняемый код клиенту (классика — JS в браузере), расширяя функциональность клиента.
В API это редкость, но в “вебе” как части REST — да.

---

# Что обычно подразумевают под “REST API” на практике (чуть приземлённее)
Многие “REST API” в реальности — это REST-like: используют HTTP, ресурсы и статусы, но без HATEOAS и иногда с компромиссами по stateless.

Негласные “правила хорошего тона”:

• существительные в URL: /products, /products/{id}
• использовать HTTP-методы по смыслу:

- GET — получить (без побочек)
- POST — создать/запустить операцию
- PUT — заменить целиком (идемпотентен)
- PATCH — частично обновить
- DELETE — удалить (обычно идемпотентен)
- корректные статусы:
- 201 Created (+ Location)
- 204 No Content (например, после DELETE)
- 400/401/403/404/409/422 по ситуации

• версия API: чаще /v1/... или через заголовки (спорно, но так живут)
• пагинация/фильтры: ?page=, ?limit=, ?sort=, ?filter=
• идемпотентность для “опасных” операций (иногда Idempotency-Key для POST)

---

Если хочешь, могу на твоём примере (какая-нибудь “каталог игр/заказы/профиль”) набросать правильные эндпоинты, статусы, схемы ответов и где уместны PUT vs PATCH. Что за API делаешь и для кого (публичное/внутреннее)?