[HOW-TO] TrackMania Web Services SDK for PHP (V1.0 06/13/11)

[gouxim]

Current SDK version 1.0 (June 13th)
http://code.google.com/p/trackmania-ws- ... dk-1.0.zip

SDK Changelog

Code: Select all

1.0
- Initial public release of the SDK
! Removed TrackMania_Players::isOnline()

0.7
+ TrackMania_WebServices::$throwExceptions define whether to throw exceptions or not
+ TrackMania_WebServices::$lastException contains the last excption if throwing is disabled
! ManiaHome::sendXxxxx() methods do not throw exceptions anymore
- ManiaHome::sendXxxxToPlayer() methods are more robust (fixed a bug when the provided playerLogin
was empty)
- Fixed bug where response bodies of error cases were not JSON-decoded with PHP 5.2

Also updated examples:
+ player.bat now prompts to enter the API credentials
+ added maniahome.bat to test the posting of notifications on ManiaHome!

0.6
+ Better error handling with TrackMania_Exception::getHTTPStatusCode() & TrackMania_Exception::getHTTPStatusMessage()

0.5 - 2011, May 13th
+ Started adding documentation
! Deprecated TrackMania_Players::isOnline()
- [internals] Removed TrackMania_WebServices::executeXxx() methods ; only the execute() method is used now

0.4 - 2011, May 9th
- Fixed yet another 5.2 compat' bug

0.3 - 2011, May 9th
- Fixed 5.2 compatibility bugs

0.2 - 2011, May 6th
- Fixed bug for method with optional parameters
- Fixed handling of HTTP erros
- Increased HTTP timeout from 5s to 10s

0.1 - 2011, May 5th
+ Initial relase

1 - Requirements

In order to use the TrackMania Web Services SDK you need a few things.
* PHP 5.2 or newer
* CURL extension http://php.net/manual/en/book.curl.php
* JSON extension http://php.net/manual/en/book.json.php
* Your Web Server must be configured to that you can make HTTPS requests to external servers (namely ws.trackmania.com)

2 - Create an API user

In order to communicate with our API, you will need an API user. To do that:

* Go to http://developers.trackmania.com/webservices_users/
* Login with your TrackMania account
* Click on Create a new API user

3 - Allow your API user to access TrackMania game data

Now that you have your API user, you can make requests on the API. For example, we implemented a "test" service:

http://ws.trackmania.com/foobar/

However, a default user don't have the rights to access TrackMania game data by default. For example, you can test to call the following service with your newly created user:

https://ws.trackmania.com/tmf/players/gou1/

You should have a "forbidden" error.

To have access to TrackMania game data, you need to:
* Go to http://developers.trackmania.com/webservices_users/
* Click on "Manage" for the API User you want to use
* Click on "Request access to TMF game data"

You can verify that you actually can make requests on TMF game data by checking that your API user is in the group "tmf-pub".

4 - Download the TrackMania Web Services SDK for PHP

Download the latest version of the SDK. Check the link at the begining of the topic.

5 - Basic example

The SDK consists of several PHP classes. For simplicity's sake, we put everything in one single PHP file. Put it somewhere in your project so you can include it in your scripts.

Code: Select all

require_once '/path/to/trackmania-ws.php';

Let's say you want to retrieve some player information. The SDK contains a class called "TrackMania_Players". First, you need a instance of this class. They pretty much all take the same two first parameters: api username and password.

Code: Select all

$tmPlayers = new TrackMania_Players('your_api_username', 'your_api_password');

Let's look at the class interface:

function get($login)
function getNicknameHTML($login)
function getTags($login)
function isOnline($login)
function getMultiplayerRanking($login)
function getMultiplayerRankingForEnvironment($login, $environment)
function getSoloRanking($login)

It should be pretty straight forward. Let's say we want to retrieve player information about me:

Code: Select all

$player = $tmPlayers->get('gou1');

It will return a nice little stdClass object:

Code: Select all

Object
(
    [id] => 1364771
    [login] => gou1
    [nickname] => $w$z$o$66fg$77f๐$88fu$99f1 $000 ツ
    [united] => 1
    [path] => World|France|Ile-de-France|Paris
    [idZone] => 84
)

The complete code is very short:

Code: Select all

<?php
require_once '/path/to/trackmania-ws.php';

$tmPlayers = new TrackMania_Players('your_api_username', 'your_api_password');
$player = $tmPlayers->get('gou1');

var_dump($player);
?>

6 - Error handling

The service classes throws a TrackMania_Exception in case of error. This exception stores the message & code if they were found in the response body, plus the HTTP status code & message.

He're an example of how to use that to get useful information for debugging:

Code: Select all

<?php
require_once '/path/to/trackmania-ws.php';

try
{
    $tmPlayers = new TrackMania_Players('your_api_username', 'your_api_password');
    $player = $tmPlayers->get('gou1');

    var_dump($player);
}
catch(TrackMania_Exception $e)
{
    printf("HTTP Response: %d %s\n", $e->getHTTPStatusCode(), $e->getHTTPStatusMessage());
    printf("API Response: %s (%d)\n", $e->getMessage(), $e->getCode());
}

?>

Please note that the error behaviour is different in the ManiaHome class. The sendXxxx() methods do not throw exceptions. Check the provided example to see how it works. This was done to keep compatibility with the ManiaHome SDK for PHP (which will be probably merged with the TM WS SDK when it's public).

7 - API Documentation

The SDK API Documentation is available at:

http://trackmania-ws-sdk.googlecode.com ... index.html

You can also check the returns types in this topic:

http://forum.maniaplanet.com/viewtopic.php?f=206&t=1512

8 - Feedback

We'd love to hear your feedback and questions so we can improve everything. So don't hesitate to create topics to post your questions !

[musterman]

Small problem :

[fastforza]

This would be in relation to the current state of the TMWS API which appears to be broken at the moment. It's in French so I can only guess.

[gouxim]

Yes indeed there's a problem on our mysql server that is affecting lots of services. I'm tryin to fix the problem.

Edit: it is fixed

[gouxim]

Somes services (including the API) will be down for about an hour for maintenance (follow up to this week end downtime). I'll keep you posted when everything is back online.

EDIT: everything is back online

[musterman]

ok