API-first – это когда сначала проектируется и согласуется API (контракт), и только потом начинается разработка.
Что такое API в этом контексте? Это контракт взаимодействия между системами, где зафиксировано:
• какие есть методы (endpoint’ы)
• какие данные приходят (request)
• какие данные возвращаются (response)
• какие есть ошибки
• при каких условиях всё это работает
Если говорить простым языком, в контракте написано, как системы будут общаться друг с другом.
Зачем это нужно?
API-first упрощает жизнь команде, так как frontend и backend могут работать параллельно, меньше переделок на этапе разработки (т.к. изначально всё продумано и описано), соответственно, меньше сюрпризов на проде.
Роль аналитика в API-first – ключевая, т.к. именно он продумывает логику взаимодействия системы:
1. Определяет сущности и действия
Сначала раскладываем, какие есть сущности (user, order, payment) и какие действия с ними происходят
2. Проектирует API-методы
Из этого уже появляются endpoint’ы:
POST /orders
GET /orders/{id}Но это ещё не API – это только каркас.
3. Описывает контракт (самое важное)
Вот здесь начинается основная работа.
Я обычно фиксирую:
• структуру запросов и ответов
• примеры payload
• обязательные и необязательные поля
• форматы данных
• коды и сценарии ошибок
Во избежание ситуации «каждый понял по-своему»…
4. Продумывает сценарии и логику
Не просто «есть метод», а четко прописываем кто его вызывает, в какой момент и что происходит дальше
5. Думает про устойчивость
Я обычно сразу задаю себе вопросы:
• что если запрос придёт дважды?
• что если сервис не ответит?
• можно ли повторять запрос?
То есть идемпотентность, ошибки, retry – всё это закладывается на этом этапе.
6. Согласует API с командой
Обязательно прохожу контракт с разработчиками и тестировщиками, т.к. разработчик скажет, где сложно, а QA сразу найдёт дыры
7. Фиксирует контракт
И только после этого API считается «готовым».
Важно! если API постоянно меняется – это уже не API-first.