Публичный API: документация, лимиты, ключи
↑ 5.1 Проектирование REST API · ← Предыдущая
Зачем это на собесе
Что нужно, чтобы API могли безопасно использовать внешние разработчики.
Объяснение
| Аспект | Практика |
|---|---|
| Документация | OpenAPI + примеры, гайд быстрого старта, changelog, коды ошибок |
| Аутентификация | API-ключи для простых сценариев, OAuth 2.0 для доступа от имени пользователя |
| Лимиты | rate limit по ключу/плану, заголовки X-RateLimit-*/Retry-After, ответ 429 |
| Квоты и тарифы | суточные/месячные лимиты, биллинг |
| Безопасность | HTTPS, минимальные права ключей (scopes), ротация, IP allowlist |
| Наблюдаемость | логирование по ключам, метрики использования, алерты на аномалии |
| Песочница | тестовое окружение с фиктивными данными |
| SDK | генерация клиентов из OpenAPI |
| Вебхуки | подписи и повторы (см. Вебхуки: приём, подпись, повторы, идемпотентность) |
builder.Services.AddRateLimiter(o => o.AddPolicy("by-key", ctx =>
RateLimitPartition.GetTokenBucketLimiter(ctx.Request.Headers["X-Api-Key"].ToString(),
_ => new TokenBucketRateLimiterOptions { TokenLimit = 100, TokensPerPeriod = 10, ReplenishmentPeriod = TimeSpan.FromSeconds(1) })));Нюансы и подводные камни
- Ключ храните хэшированным, показывайте только один раз.
- Прозрачные, стабильные ошибки и коды — часть контракта.
- Вводите лимиты с самого начала: снять ограничения проще, чем добавить.
- Разделяйте публичный и внутренний API, не выставляйте внутренние endpoint-ы.
- Планируйте депрекацию и версионирование до первых клиентов.
Практика
- Добавьте API-ключи с scopes и лимитами по плану.
- Опубликуйте OpenAPI в Scalar/Swagger UI с примерами.
- Соберите дашборд использования по ключам.
Вопросы с ответами
API-ключ или OAuth?
Ключ — для доступа приложения; OAuth — когда нужен доступ от имени пользователя с ограниченными правами.
Как сообщить клиенту о лимите?
Ответом 429 с заголовком
Retry-Afterи информацией об остатке квоты.