# Как создать API с помощью ИИ: REST-бэкенд шаг за шагом

URL: https://agentvera.dev/ru/blog/build-api-with-ai/ · Опубликовано: 2026-10-25

Как создать API с помощью ИИ: выбор стека, схема и миграции, аутентификация, валидация, тесты, OpenAPI, деплой и ошибки безопасности, которые делают агенты.

**Коротко:**

- Сначала запишите ресурсы, эндпоинты, формат ошибок и правила в CLAUDE.md или AGENTS.md, затем пусть агент строит по одному ресурсу за раз, с тестами и коммитом после каждого шага.
- Валидируйте каждое тело запроса по схеме, меняйте базу только через миграции и проверяйте на сервере, что запись принадлежит вызывающему, а не только то, что он вошёл в систему.
- Генерируйте документацию OpenAPI из тех же схем, запускайте миграции отдельным шагом деплоя и покажите аутентификацию, авторизацию и работу с данными разработчику до прихода реальных пользователей.

Создать API с помощью ИИ можно за один вечер: попросите [агента программирования](/ru/glossary/coding-agent/) вроде Claude Code или Codex сделать «REST API для задач с пользователями», и вы получите маршруты, базу данных и запущенный сервер. Переживёт ли этот API первых реальных пользователей — другой вопрос. Обычные проблемы: непроверенный ввод, эндпоинты, раздающие чужие данные, и миграции, которые никто не читал. В этой статье я показываю, как строю REST-бэкенд с агентами, от выбора стека до деплоя, и где стоит притормозить.

Это часть серии, которая началась со статьи [SaaS MVP с помощью ИИ](/ru/blog/build-saas-mvp-with-ai/). Та статья о продукте, эта — о бэкенде под ним, к которому обращаются мобильное приложение, фронтенд или другие сервисы. Если такой способ работы для вас в новинку, для разминки подойдёт статья [как заниматься вайб-кодингом](/ru/blog/how-to-vibe-code/).

## 1. Опишите API до кода

API — это контракт. Как только под него выпущено мобильное приложение, переименование поля обходится дорого. Поэтому до того, как агент напишет код, запишите:

- **Ресурсы:** существительные. Например, `users`, `projects`, `tasks`, `comments`.
- **Эндпоинты:** `GET /v1/projects`, `POST /v1/projects`, `GET /v1/projects/:id/tasks`, `PATCH /v1/tasks/:id` и так далее.
- **Кто что может:** «Участники проекта читают его задачи; удалить проект может только владелец».
- **Формат ошибок:** одна форма для всех ошибок, с HTTP-статусом, машиночитаемым кодом и сообщением.
- **Пагинация:** курсор или страницы, размер страницы по умолчанию и максимальный.

В первой версии оставьте только эндпоинты, которые нужны реальному клиенту. Админский API, вебхуки и массовый импорт подождут.

## 2. Запишите правила в файл спецификации

Агенты не помнят прошлых разговоров. Claude Code читает `CLAUDE.md` в начале каждой сессии; Codex и многие другие агенты читают `AGENTS.md`. Запишите туда свои решения:

```markdown
# Tasks API

## Stack
- Node.js LTS, TypeScript, Fastify
- PostgreSQL, Prisma for schema and migrations
- Zod for request validation; OpenAPI generated from the same schemas
- Vitest; tests use app.inject() against a test database

## Rules
- All routes under /v1. JSON only.
- Every request body, query and param is validated with a schema.
- Errors: { "error": { "code": "...", "message": "..." } }, never a stack trace.
- Every query on tasks and projects checks project membership.
- Never return password hashes or tokens; use explicit response schemas.
- Database changes only through migration files.
- List endpoints: cursor pagination, default 20, max 100.
- Secrets come from environment variables; never in code or logs.
- Ask before adding a dependency.
- After every task: pnpm lint && pnpm test

## Out of scope (for now)
Admin API, file uploads, webhooks, GraphQL.
```

Каждое правило здесь появилось потому, что без него агенты ошибаются. «Явные схемы ответов» не дают агенту вернуть всю строку пользователя вместе с хешем пароля. «Максимум 100» не даёт кому-то запросить миллион строк. Подробнее о том, как писать этот файл, — в статье [CLAUDE.md и AGENTS.md](/ru/blog/claude-md-agents-md/).

## 3. Выберите скучный стек

Агент пишет код лучше на стеке, который видел тысячи раз. Два безопасных варианта:

| | TypeScript | Python |
| --- | --- | --- |
| Фреймворк | Fastify (или Express, Hono) | FastAPI |
| Валидация | Zod или JSON Schema | Pydantic |
| Доступ к базе | Prisma или Drizzle | SQLAlchemy |
| Миграции | Prisma Migrate, Drizzle Kit | Alembic |
| OpenAPI | @fastify/swagger | Встроено |
| Тесты | Vitest + `app.inject()` | pytest + `TestClient` |

Оба работают. Берите язык, который можете читать, потому что читать диффы придётся много. В примерах я использую TypeScript, Fastify, Prisma и PostgreSQL.

Запустите Postgres локально в Docker, чтобы агенту никогда не понадобилась общая база:

```bash
docker run --name tasks-db -e POSTGRES_PASSWORD=dev -p 5432:5432 -d postgres:16
mkdir tasks-api && cd tasks-api && git init
```

## 4. Сначала план, потом по одному ресурсу

Первым промптом я прошу план, а не код:

```text
Read CLAUDE.md. Don't write code yet.
Propose:
1. The Prisma schema (models, relations, indexes, unique constraints)
2. The full endpoint list with request and response shapes
3. How authorization works for each endpoint
4. 6–8 implementation steps, each ending with tests that pass
List open questions at the end.
```

Поправьте план, ответьте на вопросы, обновите спецификацию. Дальше — шаг за шагом:

```text
Implement step 2: the projects resource (list, create, get, update,
delete). Validate input with Zod, use explicit response schemas,
check membership on every query. Write tests for the happy path,
invalid input, and a second user who is not a member. Run the tests,
show me the result, then stop.
```

«Then stop» нужно, чтобы я прочитал дифф и закоммитил до следующего шага. Когда агент уходит не туда, я откатываюсь на один коммит, а не распутываю пять ресурсов.

## 5. Схема и миграции

Схему труднее всего менять потом, поэтому читайте её внимательно:

- **Ограничения в базе, а не только в коде.** `NOT NULL`, уникальные email, внешние ключи с осознанно выбранным поведением `ON DELETE`.
- **Индексы под ваши запросы.** Каждый внешний ключ, по которому вы фильтруете, и каждый столбец, по которому сортирует эндпоинт списка.
- **Временные метки** (`createdAt`, `updatedAt`) в каждой таблице; они помогают при отладке и курсорной пагинации.
- **Деньги — целыми числами или decimal**, никогда не числами с плавающей точкой.

Любое изменение проходит через миграцию:

```bash
npx prisma migrate dev --name add_tasks   # create and apply locally
npx prisma migrate reset                  # rebuild the dev database from zero
npx prisma migrate deploy                 # apply pending migrations in production
```

Как только появились реальные данные, читайте каждый файл миграции, который пишет агент. Останавливайтесь и задавайте вопросы при виде `DROP COLUMN`, `DROP TABLE`, переименований (Prisma может превратить их в удаление и добавление), `UPDATE` или `DELETE` без `WHERE` и новых столбцов `NOT NULL` без значения по умолчанию в больших таблицах.

## 6. Аутентификация: берите готовое

Не поручайте агенту изобретать хранение паролей или формат токенов. Используйте облачный сервис аутентификации или известную библиотеку, а задача агента — подключить её:

- **Пароли** хешируются argon2 или bcrypt через поддерживаемую библиотеку и никогда не хранятся и не логируются в открытом виде.
- **Сессии или токены:** для браузерного клиента на том же сайте самый простой безопасный вариант — сессионная cookie с `HttpOnly`, `Secure` и `SameSite`. Для мобильных и сторонних клиентов — короткоживущие access-токены с refresh-токенами.
- **Проверяйте токены как следует.** Подпись, срок действия, издатель и аудитория; алгоритм `none` отклоняется. Попросите агента показать, где именно это происходит.
- **Ограничьте частоту входа и сброса пароля**, чтобы никто не мог перебрать тысячи паролей.

## 7. Авторизация: ошибка, которую агенты пишут чаще всего

Аутентификация отвечает на вопрос «кто это?». Авторизация — «можно ли ему трогать эту запись?». В API, написанных агентами, первое обычно сделано правильно, а второе — нет. Классический пример: `GET /v1/tasks/:id` проверяет, что токен валиден, и загружает задачу по ID. Любой вошедший пользователь читает любую задачу, просто меняя число. OWASP ставит эту уязвимость, broken object level authorization, на первое место в API Security Top 10.

Исправление — это привычка, а не библиотека:

- Каждый запрос, загружающий запись по ID, также фильтрует по тому, к чему у вызывающего есть доступ: `where: { id, project: { members: { some: { userId } } } }`.
- «Не найдено» и «не ваше» возвращают одинаковый `404`, чтобы ID нельзя было перебирать.
- **Проверяйте двумя пользователями** каждый эндпоинт, который принимает ID. Эти тесты — самые ценные в проекте.

Родственная ошибка — mass assignment: агент передаёт тело запроса прямо в `update()`, а пользователь присылает `"role": "admin"` или `"ownerId": "..."`. Это останавливают схемы валидации, в которых перечислены только разрешённые поля.

Спросите агента: «List every endpoint and the authorization check it performs. Mark any endpoint that loads a record by ID without filtering by the caller.»

## 8. Валидация и ошибки

Всё, что пересекает границу, проходит валидацию: тело, строка запроса, параметры пути, заголовки, которые вы используете. С Zod и Fastify маршрут объявляет свои схемы, и невалидные запросы отклоняются с `400` ещё до вашего кода.

- **Отклоняйте неизвестные поля**, а не игнорируйте их молча; так ошибки клиентов всплывают раньше.
- **Ограничьте размеры:** длину строк и массивов, размер тела запроса, размер страницы.
- **Одна форма ошибок** для всего и глобальный обработчик, который логирует подробности на сервере, а клиенту возвращает только `code` и `message`. Стектрейсы и ошибки SQL в ответах — это карта для атакующего.
- **Только параметризованные запросы.** ORM делает так по умолчанию; следите за хелперами сырого SQL со склейкой строк, например `$queryRawUnsafe` в Prisma.

## 9. Тесты, которые имеют значение

`app.inject()` в Fastify отправляет запросы в приложение, не открывая порт, поэтому тесты API быстрые. 100% покрытия не нужно; нужны вот эти:

1. **Успешный сценарий каждого эндпоинта** с проверкой статуса и формы ответа.
2. **Невалидный ввод** возвращает `400` в вашем формате ошибок.
3. **Без токена** — `401`; **чужая запись** — `404`.
4. **Пагинация** соблюдает максимум.
5. **Миграции применяются с нуля** на чистой базе.

Тесты работают с отдельной тестовой базой, которая сбрасывается между запусками. Не подпускайте тесты к учётным данным продакшена.

Следите, чтобы агент не «чинил» падающий тест, меняя проверку. Если в диффе появился тестовый файл, о котором вы не просили, спросите почему. В статье [ревью кода с ИИ](/ru/blog/ai-code-review/) есть чек-лист для этого.

## 10. Документация OpenAPI из тех же схем

Документация, написанная вручную, расходится с кодом. Генерируйте её из схем валидации, тогда она описывает ровно то, что код принимает. В Fastify `@fastify/swagger` строит документ OpenAPI из схем маршрутов, а `@fastify/swagger-ui` его отдаёт; FastAPI делает это из коробки.

```text
Add @fastify/swagger and @fastify/swagger-ui. Generate the OpenAPI
document from the existing route schemas, add descriptions and
examples, document the error format and auth. Serve the UI at /docs
only when NODE_ENV is not production.
```

Файл OpenAPI полезен не только как документация: агенты фронтенда генерируют по нему типизированный клиент, а другие инструменты находят по нему ваши эндпоинты.

## 11. Деплой

Небольшой API отлично работает как контейнер на платформе вроде Fly.io, Railway или Render либо на любом сервере с Docker. Чек-лист:

- **Dockerfile** с многоэтапной сборкой и пользователем без прав root. Попросите агента написать его, затем прочитайте.
- **Миграции отдельным шагом** (`prisma migrate deploy`) до запуска новой версии, а не в каждом экземпляре приложения при старте.
- **Переменные окружения** для URL базы, секретов и разрешённых источников CORS задаются на платформе, а не в образе.
- **Эндпоинт здоровья** (`/health`), который может проверять платформа.
- **CORS** только для ваших настоящих фронтендов; никогда `*` вместе с учётными данными.
- **Только HTTPS**, заголовки безопасности (например, через `@fastify/helmet`) и логирование запросов без паролей, токенов и персональных данных.
- **Резервные копии** продакшен-базы включены, и восстановление хотя бы раз проверено.
- **Отслеживание ошибок**, например Sentry, чтобы узнавать о `500` раньше, чем вам напишут пользователи.

## В чём ошибается ИИ

- **Возвращает строки базы целиком.** Хеши паролей, внутренние флаги и email других пользователей в JSON. Лечится явными схемами ответов.
- **Выдумывает API.** Функции библиотек, которых нет или которые изменились несколько версий назад. Давайте агенту актуальную документацию и вставляйте ошибки как есть.
- **Нет пагинации.** `findMany()` без лимита работает, пока в таблице не наберётся 200 000 строк.
- **Запросы N+1.** Отдельный запрос на каждый элемент в цикле. Попросите агента логировать запросы в разработке и ищите повторы.
- **Проглоченные ошибки.** `catch {}`, который всё равно возвращает `200`.
- **Секреты в коде.** Захардкоженный JWT-секрет «пока что», который уезжает в продакшен.
- **Расползание объёма.** «Я ещё добавил админский эндпоинт». Откатите или вынесите в отдельную ветку.

## Безопасность: коротко, но серьёзно

- Держите `.env` в `.gitignore`; меняйте любой ключ, который хоть раз попал в коммит.
- Не вставляйте API-ключи в чат; агенту достаточно имени переменной.
- Направляйте агента на локальную или staging-базу, никогда на продакшен.
- Читайте команды, которые запускает агент, особенно команды базы данных, `rm`, force push и `curl … | sh`.
- Время от времени запускайте `pnpm audit` (или аналог вашего пакетного менеджера) и отдавайте вывод агенту.
- Ограничивайте частоту запросов на всех публичных эндпоинтах, а не только на входе.

Подробнее о том, как держать агентов в безопасности на своей машине, — в статье [безопасность ИИ-агентов для программирования](/ru/blog/ai-coding-agent-security/).

## Когда подключить живого разработчика

Несколько часов ревью от опытного бэкенд-разработчика окупаются:

- До регистрации реальных пользователей — для аутентификации и авторизации
- Когда API хранит персональные, медицинские или платёжные данные
- Когда с ним будет интегрироваться партнёр или корпоративный клиент
- Когда падает производительность: медленные запросы, нет индексов, лимиты соединений
- Когда вы с агентом трижды не смогли исправить один и тот же баг

Облегчите ему задачу: файл спецификации, документ OpenAPI, папка с миграциями и зелёный прогон тестов.

## Как я делаю это в AgentVera

Всё это работает в одном терминале. Когда агентов несколько, AgentVera помогает вот где:

- **Параллельная работа в worktree.** В [рабочем пространстве](/ru/features/workspace/) я запускаю одного агента на API, а другого на фронтенд или тесты, каждого в своём [git worktree](/ru/glossary/git-worktree/), чтобы они не трогали файлы друг друга. Метод описан в статье [git worktree для параллельных агентов](/ru/blog/git-worktree-parallel-agents/).
- **Проверка эндпоинтов без отдельного инструмента.** [API-клиент](/ru/features/api-client/) находит эндпоинты проекта в файлах OpenAPI и в маршрутах Express, Fastify, Hono, Next.js, FastAPI, Django, NestJS и других. Я отправляю запрос с параметрами, заголовками и телом, а если в ответ пришла ошибка, одним кликом передаю запрос и ответ агенту.
- **Что попало в базу.** [Менеджер баз данных](/ru/features/database-manager/) открывает локальный Postgres, и я проверяю строки, которые создал агент, а [DB Guard](/ru/features/db-guard/) оценивает риск каждой миграции, когда агент завершает ход, и может прогнать её на теневой базе.
- **Контейнеры.** [Страница Docker](/ru/features/docker/) показывает контейнер Postgres и его логи рядом с агентами.
- **Ревью ходов.** [Ревью кода](/ru/features/code-review/) проверяет каждый завершённый ход до слияния.

Это ускоряет цикл, но безопасным API делают по-прежнему спецификация, тесты и ваше собственное ревью.

## Итоги

Чтобы создать API с помощью ИИ, сначала определите контракт, запишите правила в `CLAUDE.md` или `AGENTS.md`, выберите распространённый стек и пусть агент строит по одному ресурсу за раз, с тестами. Валидируйте каждый ввод, меняйте базу только через миграции, проверяйте владельца каждой записи, генерируйте OpenAPI из тех же схем и запускайте миграции отдельным шагом деплоя. Перед приходом реальных пользователей получите ревью от человека. Если хотите запускать агентов бэкенда, фронтенда и тестов бок о бок, [скачайте AgentVera бесплатно](/ru/download/).

## Частые вопросы

**Можно ли создать REST API с помощью ИИ, если я не бэкенд-разработчик?** Рабочий API для небольшого продукта с агентом программирования создать можно, если держать объём небольшим, записать правила для агента и тестировать каждый эндпоинт. Аутентификацию, авторизацию и всё, что касается персональных или платёжных данных, перед запуском должен проверить опытный разработчик.

**Какой стек лучше всего подходит для создания API с ИИ?** Распространённый, который агенты видели много раз: TypeScript с Fastify или Express либо Python с FastAPI, плюс PostgreSQL и инструмент миграций. Популярный стек означает меньше выдуманных функций и больше помощи, когда вы застрянете.

**Какая уязвимость встречается в API, написанных ИИ, чаще всего?** Отсутствие авторизации на уровне объектов: эндпоинт проверяет, что пользователь вошёл, но не проверяет, что запись принадлежит ему, поэтому смена ID в URL возвращает чужие данные. Проверяйте это двумя пользователями на каждом эндпоинте, который принимает ID.

**Стоит ли поручать ИИ писать аутентификацию с нуля?** Нет. Для паролей, сессий и токенов используйте известную библиотеку или облачный сервис аутентификации. Пусть агент подключит его и напишет правила авторизации, которые специфичны для вашего приложения, а эти правила тщательно протестируйте.

**Как получить документацию OpenAPI для API, созданного с ИИ?** Попросите агента генерировать её из тех же схем, что валидируют запросы, например через @fastify/swagger в Fastify или встроенную документацию FastAPI. Тогда документация не разойдётся с тем, что код действительно принимает.

---

**Об AgentVera.** AgentVera — настольное приложение для macOS, Windows и Linux от Solviera Teknoloji. Оно запускает 18 ИИ-агентов для программирования (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) рядом, по проектам, в настоящих терминалах с собственными установками CLI и входами пользователя. В бесплатном тарифе количество агентов не ограничено. Скачать: https://agentvera.dev/ru/download/ · Цены: https://agentvera.dev/ru/pricing/