Что такое REST API и как его правильно проектировать

Введение

REST API — один из самых распространённых способов организации взаимодействия между клиентом и сервером. Большинство современных веб-приложений и мобильных клиентов общаются с бэкендом именно через REST. Чтобы грамотно проектировать такие интерфейсы, нужно понять базовые принципы архитектурного стиля REST и научиться применять их на практике.

Что такое REST

REST расшифровывается как Representational State Transfer — передача состояния представления. Это не протокол и не стандарт, а набор архитектурных ограничений, сформулированных Роем Филдингом в 2000 году. API, которое следует этим ограничениям, называют RESTful.

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

• Клиент-серверная архитектура — клиент и сервер независимы и общаются через стандартный интерфейс.
• Отсутствие состояния (stateless) — каждый запрос содержит всю информацию для его обработки. Сервер не хранит контекст между запросами.
• Кэшируемость — ответы сервера должны явно указывать, можно ли их кэшировать.
• Единообразие интерфейса — ресурсы идентифицируются через URI, взаимодействие происходит через стандартные HTTP-методы.
• Многоуровневая система — между клиентом и сервером могут быть промежуточные узлы: прокси, балансировщики.

HTTP-методы и их назначение

REST использует стандартные методы HTTP для описания действий над ресурсами:

Пример запросов для работы с пользователями:

# Получить список всех пользователей
GET /users

# Получить конкретного пользователя
GET /users/42

# Создать нового пользователя
POST /users
Content-Type: application/json

{
  "name": "Иван Петров",
  "email": "ivan@example.com"
}

# Частично обновить данные пользователя
PATCH /users/42
Content-Type: application/json

{
  "email": "ivan.new@example.com"
}

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

Правильное проектирование URL-маршрутов

Одна из самых важных частей REST — правильное именование ресурсов.

Используйте существительные во множественном числе:

# Правильно
GET /articles
GET /articles/5

# Неправильно — глаголы в URL
GET /getArticles
POST /createArticle

Вложенные ресурсы отражают иерархию:

# Все комментарии конкретной статьи
GET /articles/5/comments

# Конкретный комментарий статьи
GET /articles/5/comments/12

Фильтрация, сортировка и пагинация — через query-параметры:

# Фильтрация по категории
GET /articles?category=javascript

# Сортировка с пагинацией
GET /articles?sort=createdAt&order=desc&page=2&limit=10

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

Правильное использование статус-кодов — признак хорошо спроектированного API:

# Успешные ответы
200 OK                   — стандартный успех
201 Created              — ресурс создан (ответ на POST)
204 No Content           — успех без тела ответа (ответ на DELETE)

# Ошибки клиента
400 Bad Request          — некорректный запрос
401 Unauthorized         — не авторизован
403 Forbidden            — доступ запрещён
404 Not Found            — ресурс не найден
422 Unprocessable Entity — ошибка валидации данных

# Ошибки сервера
500 Internal Server Error — внутренняя ошибка сервера
503 Service Unavailable   — сервис временно недоступен

Пример обработки ошибок на Node.js с Express:

app.get('/articles/:id', async (req, res) => {
  const article = await Article.findById(req.params.id);

  // Возвращаем 404, если статья не найдена
  if (!article) {
    return res.status(404).json({
      error: 'Статья не найдена',
      code: 'ARTICLE_NOT_FOUND'
    });
  }

  res.status(200).json({ data: article });
});

Формат ответов и версионирование

Единообразный формат ответов упрощает работу клиентов с API:

{
  "data": {
    "id": 42,
    "name": "Иван Петров",
    "email": "ivan@example.com"
  },
  "meta": {
    "requestId": "abc-123"
  }
}

Для списков с пагинацией:

{
  "data": [],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 245,
    "pages": 25
  }
}

Версионирование позволяет вносить изменения без поломки существующих клиентов. Самый распространённый подход — версия в URL:

/api/v1/users
/api/v2/users

Альтернатива — версия в заголовке запроса:

Accept: application/vnd.api+json;version=2

Частые ошибки

Глаголы в URL вместо существительных

REST строится вокруг ресурсов, а не действий — для действий есть HTTP-методы.

# Плохо
POST /createUser
POST /deleteUser/42
GET  /getUserById?id=42

# Хорошо
POST   /users
DELETE /users/42
GET    /users/42

Игнорирование HTTP-кодов

Возвращать 200 OK с {"error": "not found"} в теле — антипаттерн. Клиенты ориентируются на статус-код, а не только на тело ответа.

Отсутствие пагинации

Возвращать тысячи записей одним запросом — проблема производительности. Всегда добавляйте пагинацию для коллекций ресурсов.

Несогласованное именование полей

Выбирайте одну конвенцию и придерживайтесь её во всём API:

// Плохо — смешение стилей
{ "userId": 1, "user_name": "Иван", "UserEmail": "ivan@example.com" }

// Хорошо — единый camelCase
{ "userId": 1, "userName": "Иван", "userEmail": "ivan@example.com" }

Хранение состояния на сервере

REST требует stateless-архитектуры. Не храните данные о сессии в памяти сервера — используйте JWT или другие механизмы передачи состояния через запрос.

Заключение

REST API — это не просто способ передачи данных, а архитектурный стиль, который при правильном применении делает интерфейс интуитивным, масштабируемым и удобным в поддержке. Главные принципы: ресурсы идентифицируются через URL, действия описываются HTTP-методами, статус ответа отражается кодом, формат ответов единообразен. Следуя этим правилам, вы создадите API, с которым будет приятно работать как фронтенд-разработчикам, так и сторонним потребителям вашего сервиса.