Готов ли твой 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 готов к разработке, если:
✅ цели понятны
✅ интерфейс прозрачен
✅ поведение предсказуем
✅ потребителю не нужно гадать

❗️ Если что-то из этого под вопросом — возвращайтесь к обсуждению.

#навыкАналитика #REST #api #чек_лист #проектирование #IT