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

Что такое договор API и DTO?

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

Договор API описывает адрес, метод, входные данные, успешный ответ и возможные ошибки. DTO — объект, специально подготовленный для передачи между клиентом и сервером.

Вопрос

Что такое договор API и DTO? Почему нельзя возвращать клиенту строку таблицы как есть?

Основная идея

DTO расшифровывается как Data Transfer Object, то есть объект передачи данных.

Почему не стоит возвращать строку таблицы

В базе может храниться:

type UserRow = {
  id: number;
  email: string;
  passwordHash: string;
  isBlocked: boolean;
  createdAt: Date;
};

Клиенту нужна только безопасная часть:

type UserResponse = {
  id: number;
  email: string;
  isBlocked: boolean;
  createdAt: string;
};
 
function toUserResponse(user: UserRow): UserResponse {
  return {
    id: user.id,
    email: user.email,
    isBlocked: user.isBlocked,
    createdAt: user.createdAt.toISOString(),
  };
}

Пример договора

POST /api/users
 
Тело:
{
  "name": "Анна",
  "email": "anna@example.com"
}
 
Успех: 201
{
  "data": {
    "id": 42,
    "name": "Анна",
    "email": "anna@example.com"
  }
}
 
Ошибки:
400 VALIDATION_ERROR
409 EMAIL_ALREADY_EXISTS
500 INTERNAL_ERROR

Тип TypeScript не является договором во время работы

const body = request.body as CreateUserInput;

as только убеждает TypeScript и ничего не проверяет. Для настоящей границы нужен Zod или другое средство проверки.

Версионирование

Для небольшого проекта не нужно начинать с нескольких версий. Если несовместимое изменение всё же требуется, распространённый вариант:

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

Сначала попробуй добавить необязательное поле или новый маршрут без поломки старого клиента.

Документирование API

Даже короткая таблица в README полезна. В более крупном проекте договор описывают через OpenAPI, из которого можно построить интерактивную документацию и типы клиента.

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

  • Договор описывает адрес, метод, вход, успешный ответ и возможные ошибки маршрута.
  • DTO отделяет внешний формат от схемы базы: можно менять таблицу, не ломая клиента.
  • Приведение as UserDto ничего не проверяет во время работы — данные проверяет схема.
  • Договор удобно описывать в OpenAPI и генерировать из него документацию и типы клиента.
  • Несовместимое изменение согласуют с клиентами или выпускают новую версию API.

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

  • Договор описывает вход, выход и ошибки маршрута.
  • DTO отделяет внешний ответ от внутренней модели.
  • Никогда не возвращай passwordHash и другие секретные поля.
  • Приведение as не проверяет сетевые данные.
  • Несовместимое изменение требует согласования или новой версии API.

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

OpenAPI Specification, Zod: Basics, Zod: API.

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

Поиск

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