re:re:actable
Урок 012 минуты чтения

Как проектировать REST API в Express?

На этой странице
Кратко

REST API удобно строить вокруг ресурсов. Адрес называет ресурс, HTTP-метод задаёт действие, код ответа описывает результат, а JSON содержит данные или ошибку.

Вопрос

Как спроектировать REST API в Express? Чем отличаются PUT и PATCH и что такое идемпотентность?

Ресурс пользователя

GET    /api/users       получить список
GET    /api/users/:id   получить одного
POST   /api/users       создать
PATCH  /api/users/:id   частично изменить
DELETE /api/users/:id   удалить

Пути обычно называют существительными во множественном числе.

Вложенные ресурсы

GET  /api/users/42/tasks
POST /api/users/42/tasks

Не создавай слишком глубокую вложенность:

Сложно: /companies/1/departments/2/users/3/tasks/4/comments
Проще:  /tasks/4/comments

PUT и PATCH

PUT   /users/42 → полное новое представление пользователя
PATCH /users/42 → только изменяемые поля

В небольших приложениях чаще встречается PATCH.

Идемпотентность

Идемпотентная операция после повторного выполнения оставляет систему в том же состоянии.

МетодОбычно идемпотентен
GETДа
PUTДа
DELETEДа
POSTНет
PATCHЗависит от изменения

Повторный POST /orders может создать два заказа. Для денежных и других важных операций используют ключ идемпотентности или уникальное ограничение.

Не возвращай всё подряд

Ответ API — отдельный договор, а не копия внутренней таблицы.

function toUserResponse(user: UserRow) {
  return {
    id: user.id,
    name: user.name,
    email: user.email,
    createdAt: user.createdAt.toISOString(),
  };
}

Поле passwordHash, внутренние признаки и служебные ключи в ответ не попадают.

Согласованность

Выбери правила и соблюдай их во всём API:

  • единый формат дат;
  • одинаковые имена полей;
  • единый формат ошибок;
  • одинаковая пагинация;
  • предсказуемые коды ответа.

Что важно помнить

  • Ресурсы называют существительными во множественном числе: /api/users, /api/users/:id/tasks.
  • GET, PUT и DELETE идемпотентны: повтор не меняет результат; повторный POST может создать дубликат.
  • Ответ API — это DTO, а не строка таблицы: служебные и секретные поля в него не попадают.
  • Единые правила адресов, кодов и формата ошибок важнее любого отдельного решения.

Мини-шпаргалка

  • Адрес называет ресурс, метод задаёт действие.
  • Используй существительные во множественном числе.
  • PATCH меняет часть ресурса, PUT заменяет целиком.
  • Повторный POST может создать дубликат.
  • Ответ API не обязан повторять строку базы данных.

Документация

MDN: HTTP request methods, MDN: Idempotent, Express: Routing.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам