Everything I know about good API design

Краткое руководство по хорошему API-дизайну

Хороший API — это скучный API. Пользователю должно быть интуитивно понятно, как им пользоваться, без чтения документации. Однако, в отличие от большинства систем, API почти нельзя менять: любое изменение ломает чужой код и толкает клиентов к конкурентам.

Не ломаем userspace

Добавлять поля можно.
Удалять, менять тип или структуру полей — нельзя.
Даже опечатка в HTTP-заголовке referer навсегда останется опечаткой, потому что «мы не ломаем userspace».

Как изменять API без боли

Если изменение критично, используйте версионирование:

Параллельно запускаем старую (/v1/) и новую (/v2/) версии.
Сообщаем клиентам, ждём месяцы или годы, затем выключаем старую.
Stripe и OpenAI делают именно так, но это всё равно «зло из необходимости»: путает пользователей и усложняет поддержку.

Итог: проектируйте API так, чтобы не пришлось его трогать.

Комментарии (109)

«Никогда не ломать userspace» — это лишь половина правила: ядро Linux свободно ломает внутренние API, но стабильность обещает лишь для userspace.
Версионирование API спорно: большинство сервисов вечно живут на v1, а /v2 и выше почти не встречаются; многие советуют заложить версии сразу, другие — избегать лишних версий до последнего.
Идемпотентность обязательна: ключи лучше хранить в той же транзакции, что и изменения, а не в отдельном Redis, чтобы не терять состояние при сбоях.
Пагинация по курсору предпочтительнее индексной: она не повторяет элементы при добавлении новых данных и позволяет клиенту получать «следующую порцию» без пропусков.
Внутренние пользователи — тоже пользователи: не стоит заставлять их страдать от нестабильного API; лучше долго «собакофодить» перед публичным релизом.