Автор: Сергей Константинов · SDCast
Сергей Константинов написал книгу «The API» — бесплатную, в открытом доступе, на русском и английском. До этого разрабатывал API в Яндекс.Картах. В подкасте разбирает то, что в этой теме обычно остаётся за кадром обычных туториалов.
Центральная идея, которую Константинов проводит через всю книгу: закон больших чисел работает против автора API. Если концепцию или сигнатуру вызова можно понять неправильно — её неизбежно будут понимать неправильно всё больше людей по мере роста популярности API. Поэтому нейминг в публичном API — это не вопрос стиля и не задача code review. Это архитектурное решение: каждое имя, вышедшее наружу, становится обязательством.
Отсюда — его подход к проектированию через пирамиду контекстов. Сначала — зачем вообще нужен этот API, какую задачу он решает. Потом — абстракции и ответственность сущностей. И только в конце — конкретная номенклатура. Потому что цена ошибки на разных уровнях сильно отличается: «если исправить плохое именование сравнительно просто, то исправить неверное понимание того, зачем вообще нужен API, практически невозможно».
Отдельная тема — роль архитектора. Константинов прямо говорит: самая большая проблема в развитии API — отсутствие у руководителей продукта экспертизы в этой области. Кто-то должен владеть дизайном API целиком: не отдельными эндпоинтами, а всей системой контрактов — и этот человек должен думать как архитектор, а не как разработчик фичи.
Кому смотреть: разработчикам и архитекторам, которые проектируют публичные или платформенные API. Тем, кто принимает решения о версионировании. Тем, в чьей команде нет явного ответа на вопрос «кто отвечает за консистентность API целиком».
Из этого можно взять в работу: прежде чем назвать новый эндпоинт или поле — спроси, можно ли понять это имя неправильно. Если можно — его поймут неправильно. Это не паранойя, это математика.