Как проектировать 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/commentsPUT и 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.