Урок 102 минуты чтения
Как проектировать REST API на Node.js?
На этой странице
Кратко
REST API строится вокруг ресурсов, HTTP-методов, статус-кодов, заголовков и понятного формата ошибок. Node.js-фреймворк помогает с реализацией, но принципы API остаются HTTP-принципами.
Вопрос
Как проектировать REST API на Node.js?
Ресурсы и методы
| Действие | Метод и путь |
|---|---|
| Получить список | GET /users |
| Получить одного | GET /users/42 |
| Создать | POST /users |
| Заменить | PUT /users/42 |
| Частично обновить | PATCH /users/42 |
| Удалить | DELETE /users/42 |
Статусы
if (!user) {
res.statusCode = 404;
res.end(JSON.stringify({ message: 'User not found' }));
return;
}Для ошибок полезно иметь единый формат:
{
"message": "Validation failed",
"errors": [
{ "field": "email", "message": "Invalid email" }
]
}Pagination
GET /users?limit=20&cursor=eyJpZCI6NDJ9Для больших списков cursor pagination часто стабильнее, чем offset pagination.
Идемпотентность
| Метод | Идемпотентен? |
|---|---|
GET | да |
PUT | да |
DELETE | обычно да |
POST | обычно нет |
PATCH | зависит от операции |
Что важно помнить
- Ресурсы — существительные во множественном числе, действия — HTTP-методы.
- Возвращайте корректные статусы: 201 при создании, 204 без тела, 400/422 при ошибках валидации, 404, 409.
- Единый формат ошибок (например, RFC 9457 Problem Details), пагинация и версионирование.
- Валидируйте вход схемами (Zod, JSON Schema) и документируйте API в OpenAPI.
Мини-шпаргалка
- REST строится вокруг ресурсов.
- Используй правильные HTTP-методы.
- Ошибки возвращай в едином JSON-формате.
- Валидация input обязательна.
- Для списков нужны pagination и лимиты.
Документация
Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.