User Tools

Site Tools


howto

How to Use the API

The API relies on three members :

  • an API key,
  • a connector,
  • and a connection

API Keys

An API key is a public 256-bit key used mainly to track access usage and avoid massively concurrent calls to our infrastructure. Keys are provided on demand. Those keys are suitable for public use, for example using JavaScript. However, your key is linked to your account and should not be explicitly shared to anybody.

Public API keys only provide access to public information on the game. Access to private information may be available in the future and, in this case, will require private secret keys. However, access to private players information is subject to user's acceptance, unless existing contractual agreements.

To obtain an access key, send a simple request to api.itcg.eredan@feerik.com with details of your project, including your website URL or application name. Only non-profit projects will be authorized.

Connectors

A Connector is the URL you have to call to request information. It handles the formatting of the gathered data based on your request.

At this time, only two connectors are available, both replying using UTF-8 encoding :

Connectors support at least two parameters :

  • apiKey (mandatory) which contains your API key,
  • locale (optional) which contains the locale in which the requested data will be provided (The default locale is English).

Connections

Connections represent a port from which you can gather some information.

As an example, the server connection provides information about the server running the game, such as server time and online player count.

Connections may accept specific parameters to customize the result (for example, specific IDs or the start index and/or item-per-page count for paginated connections).

How to Build a valid request URL

A valid request URL is composed by concatenating the following members :

  • the connector URL,
  • the connection to use, prefixed with a slash (/),
  • path info parameters, if applying, each prefixed with a slash (/),
  • a question mark (?), indicating the start of a query string,
  • your API key using the apiKey parameter,
  • optionnaly, the locale parameter, prefixed with a & character,
  • query string parameters, if applying, each prefixed with a & character

The following example URL is suitable to request the JSON-formatted rarities of ID 1, 2 OR 3 in french :

http://api.itcg.eredan.com/json.php/rarities/1,2,3?apiKey=YOUR_API_KEY&locale=fr

This next example URL is suitable to request the JSON-formatted cards of classes' IDs 1 AND 2 (Cards which are usable by a warrior and a mage) in english :

http://api.itcg.eredan.com/json.php/cards/classes/1;2?apiKey=YOUR_API_KEY&locale=en

For character's caracteristics the API accept a single value or a range of values, this URL is suitable to request the JSON-formatted list of character whose spirit value is between 2 and 4.

http://api.itcg.eredan.com/json.php/cards/spirit/2-4?apiKey=YOUR_API_KEY&locale=en

As another example, this example URL is suitable to request 10 JSON-formatted cards from the 10th in default locale :

http://api.itcg.eredan.com/json.php/cards?apiKey=YOUR_API_KEY&start=10&count=10

Available locales

  • us : English (Default)
  • br : Portuguese (Brazil)
  • cn : Simplified Chinese
  • de : German
  • es : Spanish
  • fr : French
  • it : Italian
  • pt : Portuguese
  • tw : Traditional Chinese

Further Reading

howto.txt · Last modified: 2013/01/29 22:58 by admin