Эмбер Фэн рассказывает, как в Stripe разрабатывают API:

1. Используется слоистая архитектура: слой аутентификации, слой валидации, слой логики, слой обработки ошибок, слой форматирования ответа. Это позволяет при работе над эндпоинтом сосредоточиться на его логике и абстрагироваться от всего остального.
2. Документация пишется прямо в коде, а потом автоматически собирается. Так труднее забыть обновить ее.
3. Когда пользователь делает первый запрос, на сервере сохраняется, какую версию API он использует. После этого все его запросы перенаправляются на эту или совместимую версию. API меняется, но однажды настроенные интеграции никогда не ломаются. Но если нужно, можно указать нужную версию в HTTP-заголовках.
4. Для версионирования используются «гейты». Они перечислены в YAML-файле:

    -
      :version: 2014-09-24
      :new_gates:
        -
          :gate: allows_amount
          :description: >-
            Sending amount is now deprecated.

После этого в коде можно писать так:

if !user.gating(:allows_amount) && params[:amount]
    raise UserError.new("Invalid param.")
end

Гейты избавляют от необходимости работать с номерами версий в коде. Кстати, подобные проверки тоже вынесены в отдельные слои: слой совместимости запроса и слой совместимости ответа.