Готов ли твой API к разработке? 👀
7 вопросов, которые стоит задать до того, как писать первую строчку кода.
API — это не просто технический объект. Это средство общения между людьми, командами и системами. Чем понятнее это общение — тем надёжнее продукт.
1️⃣ Что делает API с точки зрения потребителя? API — не URL. Это способ достичь цели. ➖ Какую задачу решает вызов? ➖ Что происходит до и после? ➖ Что на выходе — ID, статус, результат?
❌ POST /orders ☑️ Подтвердить корзину, получить заказ и статус.
2️⃣ Кто потребитель? ➖ Микросервис, фронт, партнёр? ➖ Какие ограничения (сеть, формат, безопасность)? ➖ Прямой вызов или через фасад? От этого зависят: структура, поведение, логика, кеши.
3️⃣ Интерфейс понятен без декодера? ➖ Названия без внутреннего сленга? ➖ Методы соответствуют действиям? ➖ JSON читается без лишних телодвижений? Проверь: ты бы понял это API, будь ты новым разработчиком?
4️⃣ Данных ровно столько, сколько нужно? ➖ Что реально нужно потребителю? ➖ Не утекли ли лишние поля (внутренние ID, статусы)? ➖ Можно ли отдать сразу «готовое к отображению»? API — не экспорт из базы. Это точка входа в сценарий.
5️⃣ Как API ведёт себя в реальности? ➖ Что возвращает при успехе / ошибке / конфликте? ➖ Формат ошибок ясен? ➖ Есть ограничения: лимиты, порядок, объём? Пограничные сценарии случаются регулярно — их нужно учитывать с самого начала.
6️⃣ Не тянет ли API за собой реализацию? ➖ Не требует ли знания структуры БД? ➖ Не вызывает ли 3 метода вместо одного действия? ➖ Можно ли объяснить поведение словами, без схем?
❌ «Включить магнетрон» ☑️ «Разогреть еду»
7️⃣ Есть ли описание, которому можно доверять? ➖ Есть цели, данные, сценарии? ➖ Контракт: структура, поля, типы, ошибки? ➖ Можно ли сгенерировать мок без уточнений? Хороший API читается как документация.
API готов к разработке, если: ☑️ цели понятны ☑️ интерфейс прозрачен ☑️ поведение предсказуем ☑️ потребителю не нужно гадать
❗️ Если что-то из этого под вопросом — возвращайтесь к обсуждению.
