Руководство:
Использование API

В данном разделе представлена информация о том, как правильно использовать Wargaming.net API для создания новых приложений.

Идентификация приложения

Чтобы начать работу над созданием нового приложения, вам необходимо войти в кабинет разработчика и получить application_id. См. Кабинет разработчика.

Всего можно создать максимум 10 приложений.

На основании application_id, указанного в запросе, происходит идентификация приложения, а также выделяется определённая квота на количество выполняемых запросов.

Будьте внимательны при использовании application_id и убедитесь, что ваш ключ не стал известен третьим лицам.

Типы приложений

Существует два типа приложений, для создания которых можно использовать Wargaming.net API:

Тип приложения указывается при регистрации приложения. См. Регистрация приложения.

Серверные приложения

Серверные приложения — все внешние приложения, которые взаимодействуют с API на уровне «сервер-сервер».

Запросы от серверных приложений приходят с определённых IP-адресов. Максимальное количество разрешённых IP-адресов для одного application_id равно 5.

Для серверных приложений IP, с которого был отправлен запрос, должен соответствовать IP, который был указан при регистрации приложения.

Серверные приложения имеют свои квоты на количество одновременных запросов от приложения. См. Ограничения.

Автономные приложения

Автономные приложения — приложения, которые взаимодействуют с API на уровне «клиент-сервер». Запросы от автономных приложений приходят с различных IP-адресов .

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

Тип приложения и его описание можно отредактировать в разделе Мои приложения. Все изменения сразу вступают в силу.

Персональные данные пользователя и использование access token

В некоторых методах PAPI существует возможность получения персональных данных пользователя. Персональные данные пользователя – персональная информация игрока или клана игрока, доступная только авторизированным игрокам, которая не может быть отображена другим игрокам. Например, это информация о статусе, имуществе, приватной статистике и контактах игрока, информация клана в укрепрайоне и т.д.

Если ваше приложение использует персональные данные пользователя, ознакомьтесь с правилами использования access token.

Access token – ключ доступа к персональным данным пользователя. Имеет срок действия. Для получения ключа доступа необходимо запросить аутентификацию игрока используя специальные методы.

Получение access token в методах игры World of Tanks Xbox выдаётся после аутентификации пользователя по Windows Live ID. Чтобы войти, игрок должен ввести Live ID и пароль. Вход через сервис консолей – метод для получения access token.

Для методов игры World of Tanks PS4 access token выдаётся после аутентификации пользователя по PlayStation Network ID. Чтобы войти, игрок должен ввести PlayStation Network ID и пароль. Вход через сервис консолей – метод для получения Access token.

Для методов остальных игр и ресурсов компании Wargaming.net, которые присутствуют в кабинете разработчика, access token выдаётся после аутентификации пользователя при помощи Идентификатора Wargaming.net (OpenID), который используется в играх World of Tanks, World of Tanks Blitz, World of Warships, World of Warplanes и на сайте WarGag.ru. Игрок должен ввести email и пароль, использованные при создании аккаунта, или войти при помощи аккаунта социальной сети. Аутентификация не поддерживается для пользователя Game Center под iOS, если аккаунт не привязан к одной из социальных сетей или в профиле не указан email и пароль. Вход по Open ID – метод для получения access token.

Срок действия access token составляет две недели с момента его получения. Access token может быть действителен в течении 10 минут после «выхода» в связи с кешированием. Для продления срока действия активного access token:

Если срок действия access token не был продлён, то при обращении к персональным данным пользователя появится сообщение об ошибке, и пользователь вашего приложения будет вынужден повторно аутентифицироваться.

Если в вашем приложении предусмотрена аутентификация через:

  • Wargaming.net Open ID,
  • Windows Live ID,
  • PlayStation Network ID, то наличие функции «выход» обязательно.

Пользователь имеет возможность завершить сессию на странице «Сеансы» в «Личном кабинете», что приведёт к инвалидации access token.

В целях безопасности все запросы, содержащие access token, должны отправляться по HTTPS.

Категорически запрещается передавать access token либо персональные данные пользователя третьим лицам.

Ограничения

Для стабильной работы количество одновременных запросов к API ограничено:

  • Серверные приложения. Лимитируются по количеству запросов от приложения в секунду. На каждый указанный IP адресс лимит составляет 20 запросов в секунду.
  • Автономные приложения. Лимит выставляется на количество одновременных запросов с одного IP-адреса и составляет 10 запросов в секунду.

Увеличение лимитов

Лимиты могут быть увеличены по запросу.

Если для вашего приложения необходимо большее количество запросов в секунду, свяжитесь с нами через Центр поддержки (Европа, Северная Америка, Азия) и предоставьте следующую обязательную информацию.

  • Основная информация. Название и описание приложения, application_id и ссылки на приложение. Укажите причины запроса на увеличение квоты.
  • Использование.

    Текущее количество запросов в секунду, которое отправляет ваше приложение, способы формирования запросов, наличие фильтров по параметру fields, и другую важную, по вашему мнению, информацию.

    Такая информация может служить подтверждением необходимости увеличения квоты. По возможности предоставьте примеры запросов.

  • Кэш. Кэшируемая информация и частота обновления информации.

Правила обратной совместимости с API

Набор методов API может изменяться. Существуют два типа изменений API:

  • Совместимые. Воспринимаются приложением корректно, без дополнительной доработки.
  • Несовместимые. Требуют доработки, т.к. могут привести к нестабильной работе приложения.

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

Совместимые изменения

Сообщение о совместимых изменениях появляются непосредственно в разделе Информация по версии и предварительно не анонсируются. Ваше приложение должно корректно обрабатывать такие изменения.

Изменения в запросах:

  • Добавление нового метода.
  • Добавление по усмотрению нового параметра в запрос существующего метода.

Изменения в ответах:

  • Добавление нового поля в ответ существующего метода.
  • Изменение порядка полей в ответе.

Несовместимые изменения

Сообщение о несовместимых изменениях в API анонсируются в разделе Устаревшие поля и методы заранее. Это позволяет запланировать изменения в реализации нового функционала вашего приложении и внести необходимые правки.

Изменения в запросах:

  • Удаление метода.
  • Добавление нового обязательного параметра в запрос существующего метода.

Изменения в ответах:

  • Изменение формата ответа (отличного от JSON).
  • Изменение типа поля в ответе.
  • Удаление поля в ответе.