Справочник по API
Voice API — это REST API, который позволяет взаимодействовать с данными Voice из собственных приложений. Это основной способ взаимодействия с Voice из вашего собственного кода.
Базовый URL
https://api.iopta.org
Версии API
Некоторые версии API и шлюза больше не поддерживаются и помечены в таблице ниже как устаревшие. Попытка использовать эти версии приведет к ошибке 400 Bad Request.
Версии API
| Версия | Статус | По умолчанию |
|---|---|---|
| 1 | Доступно | Да |
Аутентификация
Аутентификацию в Voice API можно выполнить одним из двух способов:
- С помощью токена бота, который можно найти на странице ботов в настройках вашего приложения. Дополнительную информацию о ботах см. в разделе боты и учетные записи пользователей.
- С помощью Access-токена OAuth2, полученного через OAuth2 API.
Для всех типов аутентификации аутентификация выполняется с помощью Authorization HTTP-заголовка в формате Authorization: TOKEN_TYPE TOKEN.
Пример заголовка авторизации с токеном бота
Authorization: Bot MTk4NjIyNDgzNDcxOTI1MjQ4.Cl2FMQ.ZnCjm1XVW7vRze4b7Cq4se7kKWs
Пример заголовка авторизации с Access-токеном
Authorization: Bearer MTk4NjIyNDgzNDcxOTI1MjQ4.Cl2FMQ.ZnCjm1XVW7vRze4b7Cq4se7kKWs
Шифрование
Все сервисы и протоколы HTTP-уровня (например, HTTP, WebSocket) в Voice API используют TLS 1.2.
Согласованность
Voice работает в масштабах, при которых полная согласованность невозможна. Из-за этого многие операции в нашем API и между нашими сервисами являются согласованными в конечном счёте. Из-за этого действия клиента никогда не сериализуются и могут выполняться в любом порядке (если выполняются вообще). Помимо этих ограничений, события в Voice могут:
- Никогда не отправляться клиенту.
- Отправляться клиенту ровно один раз.
- Отправляться клиенту до N раз.
Клиенты должны обрабатывать события и результаты API с максимально возможной степенью идемпотентности.
HTTP API
User Agent
Клиенты, использующие HTTP API, должны указывать действительный User Agent, который содержит информацию о клиентской библиотеке и ее версии в следующем формате:
User-Agent: VoiceBot ($url, $versionNumber)
Content Type
Клиенты, использующие HTTP API, должны указывать действительный заголовок Content-Type: application/json,
application/x-www-form-urlencoded или multipart/form-data, за исключением случаев, когда указано иное. Несоблюдение этого требования приведет к ошибке 50035 "Invalid form body".
Rate Limiting
HTTP API реализует процесс ограничения и предотвращения чрезмерных запросов в соответствии с RFC 6585. Пользователи API, которые регулярно превышают и игнорируют ограничения скорости, будут лишены своих API-ключей и заблокированы на платформе. Для получения дополнительной информации об ограничении скорости запросов, пожалуйста, см. раздел Ограничения скорости.
Boolean Query Strings
Некоторые конечные точки API принимают логические значения в качестве параметров строки запроса.
Хотя не существует стандартной системы для представления логических значений в параметрах строки запроса,
Voice представляет такие случаи, используя True, true или 1 для истины и False, false или 0 для лжи.