The chapter provides the guidelines on how to create new applications using Wargaming.net API.
To start developing an application, log in to Developer Room, register your application and get application_id. See Developer Room for details.
You can create maximum 10 applications.
The application is identified by application_id specified in the request. Also, application_id indicates the application request per second limit.
Use application_id carefully and make sure that the key is not revealed to third parties.
Two types of applications that can call Wargaming.net API:
The application type is specified upon application registration. See Registering Application for details.
Server applications are all external applications that provide “server-to-server” communication with API.
All server applications requests are sent from certain IP addresses. The maximum number of authorized IP addresses for one application_id is limited to 5.
For server applications, IP addresses, from which the request is sent, should correspond to the IP addresses specified upon application registration.
The number of requests processed by server applications is limited. See Limitations for details.
Standalone applications are all applications that provide “client-to-server” communication with API.
All standalone applications requests are sent from different IP addresses.
For standalone applications, the only application_id is validated. Also, a number of requests per second processed by applications is limited.
The application type and description can be edited on My applications page.
Personal user data and the use of access tokens
Some PAPI methods provide the ability to receive personal user data. Personal user data is the personal data of a player or a player’s clan. It is available only for logged in players and is not displayed to other users. Such data includes information about statuses, in-game possessions, personal statistics, contacts, clan information from the Stronghold mode, and so on.
If your application uses personal user data, familiarize yourself with the rules of using access tokens.
An access token is a key for accessing personal user data. It is valid only within a stated time period. To receive an access token, it is necessary to use a special method that will ask the user to log in.
For the methods of World of Tanks Xbox, an access token is given after the user has logged in via Windows Live ID. To log in, users must enter a Live ID and a password. To receive an access token, use the method Sign in with console services.
For the methods of World of Tanks PS4, an access token is given after the user has logged in via PlayStation Network ID. To log in, users must enter a PlayStation Network ID and a password. To receive an access token, use the method Sign in with console services.
For the methods of other Wargaming.net games and resources represented in the Developer’s Room, an access token is given after the user has logged in via Wargaming.net ID (Open ID). This ID is used for World of Tanks, World of Tanks Blitz, World of Warships, World of Warplanes, and the WarGag.ru website. Players can log in either by providing the email address and password used when creating the account or via a social network. iOS Game Center users who have not linked their account to a social network or have not provided the email address and password in their profile will not be able to log in. To receive an access token, use the method Open ID login.
An access token is valid for two weeks after it has been received. Due to caching, an access token may be valid for only 10 minutes after it has been issued. To extend the time period during which an access token is valid:
- For the methods of World of Tanks Xbox, use the method Access token extension.
- For the methods of World of Tanks PS4, use the method Access token extension.
- For the methods of other Wargaming.net games and resources that are represented in the Developer’s Room, use the method Access token extension.
If the time period within which an access token is valid has not been extended, an error message will be displayed to the user when requesting personal data. The user will need to log in again.
Your application must provide a possibility to log out if it presupposes logging in via:
- Wargaming.net Open ID
- Windows Live ID
- PlayStation Network ID
A user can end a session on the Sessions page in the Account Management section, which will lead to the invalidation of the access token.
For security reasons, all requests containing access tokens must be sent via HTTPS.
To provide the stable service functioning, the number of requests sent to API is limited.
- Server applications. Request limit per second is set to 20 requests per second.
- Standalone applications. The limit is set on the number of requests sent from one IP address at the same time and in general equal to 10 requests per second.
Upon request, the limits can be increased.
Provide the following information in your request:
- General information. Application name and its description, application_id, and links to the application. Provide the reasons for the request per second limit increase.
Current number of requests per second your application sends, the request formats, ability to filter by fields parameter, and other relevant information.
Such information may serve as the grounds for the request limit increase. Provide the examples of requests, if possible.
- Cache. Cached information and information refresh rate.
API Backward Compatibility
The set of API methods can vary. There are two types of API changes:
- Compatible. Handled by the application correctly. The changes do not require any modification of the application.
- Incompatible. The modification of the application is required as the changes may cause any unstable application functioning.
To provide the stable application functioning, always consider the types of API changes.
The information about compatible changes is not announced beforehand and can be found under Release Notes. Your application must handle such changes correctly.
Changes in requests:
- Adding a new method.
- Adding a new optional parameter to the request format of the existing method.
Changes in responses:
- Adding a new field in the response format of the existing method.
- Changing the fields order in the response format.
The information about incompatible changes is available in Upcoming Changes well in advance. It allows you implement new functionality and make all required modifications of your application.
Changes in requests:
- Deleting a method.
- Adding a new required parameter to the request format of the existing method.
Changes in responses:
- Changing the response format (different from JSON).
- Changing the field type in response.
- Deleting a field in the response.