Какие параметры должны быть у API сервиса переводов

Что проверяют

Умеете ли вы спроектировать контракт, а не просто перечислить поля: где лежит текст, как передаётся ключ, что будет с длинным документом и неизвестным языком. Следом обычно спрашивают про пакетный перевод, лимиты и асинхронную обработку.

Как отвечать

Основной вызов POST /v1/translations с телом в JSON: текст в строке запроса упирается в длину URL и оседает в логах прокси.

• texts: массив строк, пакет закладывают сразу, десяток коротких строк одним запросом дешевле десятка запросов;
• target_lang: обязательный, код по BCP 47 (en, pt-BR);
• source_lang: необязательный, без него сервис определяет язык сам и возвращает detected_source_lang;
• format: text или html, во втором случае теги сохраняются и не переводятся;
• дополнительно: glossary_id для терминологии, formality, выбор модели.

Ответ: массив translations в том же порядке, что и входные строки, плюс определённый язык и число символов для биллинга. Рядом GET /v1/languages со списком поддерживаемых пар.

Ключ передаётся заголовком Authorization: Bearer .... Ошибки по смыслу: 422 на неподдерживаемый язык или пустой текст, 413 на превышение размера, 429 с Retry-After на лимит. Для документов нужен асинхронный режим: POST /v1/jobs отвечает 202 с идентификатором задачи, статус читается через GET /v1/jobs/{id} или приходит вебхуком.

На Python это ложится на FastAPI: модели запроса и ответа на Pydantic, коды языков через Enum, Field(max_length=...) на тексте, документация OpenAPI генерируется сама. Готовые переводы кэшируют по хэшу текста, пары языков и глоссария.

Где спотыкаются

Делают перевод через GET с текстом в строке запроса. Длинный текст обрежется, а персональные данные уйдут в логи.

Кладут api_key в URL. Он попадает в историю браузера, логи серверов и заголовок Referer.

Отвечают 404 на неизвестный язык. Ресурс /translations существует, ошибка в данных запроса, это 400 или 422.