AEPs: Как стандартизировать API и не сойти с ума

Если вы когда-нибудь пытались соединить два микросервиса от разных команд и чувствовали себя дипломатом на переговорах — у нас для вас хорошие новости.

Google представила AEPs (API Enhancement Proposals) — открытый репозиторий с рекомендациями по проектированию API. По сути, это как PEP для Python, только для API. Теперь вместо того, чтобы каждый раз изобретать велосипед с квадратными колёсами, можно заглянуть в AEPs и понять, как правильно назвать эндпоинт, какие статус-коды возвращать и как не наступить на грабли.

Первое, что бросается в глаза — AEPs не просто набор правил, а живой документ с обсуждениями. Вы можете предложить свой AEP, если вдруг обнаружили, что ваша проблема ещё не описана. Правда, готовьтесь к code review, которое может затянуться на пару недель — но это же лучше, чем потом переписывать половину бэкенда.

Что внутри?

• Именование: как называть ресурсы, чтобы не путать users с user-profiles.
• Стандартные ошибки: 404, 409, 429 — всё это уже расписано, осталось только не выдумывать свои коды.
• Пагинация: наконец-то единый подход к cursor-based и offset-based.
• Версионирование: spoiler: v1, v2 — это не всегда хорошо.

Конечно, AEPs не панацея. Если ваша команда любит хардкодить магические числа — ни один репозиторий не спасёт. Но для стартапов и зрелых проектов это отличная база, чтобы не изобретать велосипед и не ссориться на код-ревью.

Комментарий студии METABYTE: Мы в METABYTE тоже любим порядок — особенно когда API пишутся по единым стандартам. AEPs помогут вам не тратить время на споры "а как назвать этот эндпоинт", а сосредоточиться на реальной бизнес-логике. Хотя, признаемся, иногда мы всё равно используем магические числа — но только если никто не видит.