RemoteAPI

Raidplaner XHR API

General usage

The raidplaner XHR API can be accessed by calling the file "apihub.php" located in the libs folder.
You can pass a couple of different parameters to this file either via POST or by passing URL parameters.

The returned result set should be tested for an array called "error". If it does not exist (or is empty), everything went fine. Otherwise its contents will give you a hint on what went wrong.

The XHR API can also be queried for a documentation of itself by passing the "help" parameter.

Output format

The format of the returned result can be modified by the parameters "format" and "as".
"Format" can be used to switch between XML and JSON, while JSON is the default format.
"As" can be used to download the results as a file.

apihub.php?query=raid&format=xml&as=result.xml

Authentication

To use the XHR API, you will have to authenticate by using a private or a public token.
The private token can be obtained from the settings section and should not be used in situations where a third party might be able to read it. I.e. you should not use it in a javascript file that is visible for all visitors of your website. Doing so would enable everyone to read your raids, statistics, etc.

The public token should be used in situations where using the private token is not suitable.
Using the public token is a bit more complicated but allows you to decide which queries are available for all visitors of your website. Public tokens have a life time of 60 minutes and are regenerated every 30 minutes. This allows old tokens to still be used for some time, but you will already get the new token.
Public tokens are only valid for one specific call with one specific set of parameters.

Using the private key

Simply pass the private key by using the parameter "token", e.g. like this

apihub.php?query=raid&token=336e56573c28abdc

The private key can be obtained from the setting section of the raidplaner interface or via php, by including "lib/private/api.h" and calling Api::getPrivateToken().

Using the public key

You will first have to generate a public token.
You should do so in regular intervals, e.g. by loading a generated file.
This file might look like this:

<?php
    include "lib/private/api.php";
    
    $Parameter = Api::normalizeArgsRaid(Array(
        "full"    => false,
        "attends" => true
    ));
    
    $Token = Api::getPublicToken($Parameter);    
    echo $Token;
?>

This example already shows that retrieving a token requires a parameter set.
This parameter set must always by normalized before passed to Api::getPublicToken.
Normalization functions always follow the naming scheme Api::normalizeArgs<Query>, so e.g. Api::normalizeArgsRaid when you want to normalize the parameter set for the "raid" query.

The generated token will only be valid for queries using exactly the parameter set you provided.
So keep an eye on any additional white spaces and/or casing changes when having problems with the actual query using this token.

apihub.php?query=raid&full=false&attends=false&token=e25a7be57cacd25ca5fa84fae0fd77dda957759a

Please note that a generated token is guaranteed to be valid for 30 minutes. After that time it has to be regenerated.

Available commands

Querying locations

This query has no parameters and will return a list of all available locations.

apihub.php?query=location

Parameter	Default value	Example	Description
games	""	games=wow,ff14	Only return locations for specific games. Comma separated list of game ids

Querying users

This query will return character information about all or specific users.

apihub.php?query=user&games=wow

Parameter	Default value	Example	Description
users	""	users=1,2	Comma separated list of user ids to query
games	""	games=wow,ff14	Comma separated list of game names to filter characters by game
current	false	current=true	Set to true to only return the currently logged in user.

Querying raids

This query will return character information about all or specific raids.

apihub.php?query=raid&limit=5&full=false

Parameter	Default value	Example	Description
start	0	start=1392194584	Return raids starting after this UTC timestamp
end	2147483647	end=1392194584	Return raids starting before this UTC timestamp
limit	10	limit=6	Maximum number of raids to return. Passing 0 returns all raids
offset	0	offset=1	Number of raids to skip if a limit is set
raid	""	raid=1,2,3	Return only specific raids. Comma separated list of raid ids
location	""	location=onyxia,4	Return raids on specific locations. Comma separated list of location ids or names
games	""	games=wow,ff14	Return raids for specific games. Comma separated list of game ids
full	true	full=false	Do/do not return raids with all slots set
free	true	free=false	Do/do not return raids with not all slots set
open	true	open=false	Do/do not return raids which are open to attends
closed	false	closed=true	Do/do not return raids which are closed for attends
canceled	false	canceled=true	Do/do not return raids which have been canceled
attends	false	attends=true	Include list of attended players

Querying statistics

This query will return attendance information about one or multiple raids.
Players that have never attended any raid (or were set to absent) are not returned.

apihub.php?query=statistic

Parameter	Default value	Example	Description
start	0	start=1392194584	Include raids starting after this UTC timestamp
end	current timestamp	end=1392194584	Include raids starting before this UTC timestamp
users	""	users=1,2	Only count specfic users. Comma separated list of user ids
raids	""	raids=1,2	Only include specfic raids. Comma separated list of raid ids
games	""	games=wow,ff14	Only include specific games. Comma separated list of game ids