middle
Что такое API-first подход?
API-first – подход к разработке, при котором API проектируется и описывается до написания кода реализации. API становится контрактом между командами (backend, frontend, мобильные приложения, внешние системы). Это как сначала согласовать чертёж дома со всеми подрядчиками, а потом уже строить.
Порядок работы
Пример
1. Проектирование API (OpenAPI / Swagger спецификация)
│
▼
2. Обсуждение и согласование контракта между командами
│
▼
3. Генерация кода (контроллеры, клиенты, DTO)
│
▼
4. Параллельная разработка:
Backend реализует API | Frontend использует mock API
│ │
▼ ▼
5. Интеграция и тестирование
Пример OpenAPI-спецификации
Пример кода
openapi: 3.0.3
info:
title: Payment API
version: 1.0.0
paths:
/api/v1/payments:
post:
summary: Создать платёж
operationId: createPayment
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentRequest'
responses:
'201':
description: Платёж создан
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentResponse'
'400':
description: Некорректный запрос
'409':
description: Дублирование (идемпотентность)
components:
schemas:
CreatePaymentRequest:
type: object
required: [payerAccountId, payeeAccountId, amount, currency]
properties:
payerAccountId:
type: integer
format: int64
payeeAccountId:
type: integer
format: int64
amount:
type: number
format: decimal
currency:
type: string
enum: [RUB, USD, EUR]
Инструменты
- OpenAPI Generator – генерация серверного и клиентского кода из спецификации.
- Swagger UI – интерактивная документация API, позволяющая отправлять запросы из браузера.
- Spring Cloud Contract – contract testing между микросервисами.
- Prism – mock-сервер по спецификации для параллельной разработки frontend.
Плюсы и минусы
| Аспект | API-first | Code-first |
|---|---|---|
| Контракт | Определён до кода | Генерируется из кода |
| Параллельная разработка | Возможна сразу | Frontend ждёт backend |
| Источник правды | Спецификация | Код |
| Начальные усилия | Больше (проектирование) | Меньше (сразу код) |
| Согласованность | Высокая | Зависит от дисциплины |
| Автогенерация | Код из спецификации | Спецификация из кода |
Итог
API-first особенно ценен в проектах с множеством интегрируемых систем, где чёткий контракт критически важен. Подход снижает количество интеграционных багов и ускоряет параллельную разработку.
На собеседовании: Интервьюер хочет услышать понимание разницы между API-first и code-first, а также конкретные инструменты (OpenAPI Generator, Swagger). Частая ошибка – путать API-first с простым наличием Swagger-документации.