re:re:actable
Урок 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 и лимиты.

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

RFC 9457: Problem Details, OpenAPI Specification.

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

Поиск

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