Overview

The tournament_services module allows for users of the site hosting the module to access tournament data from external applications by exposing some API functions via the Services (http://drupal.org/project/services) module. This allows users of a site exposing its API with this module, for example, to post real-time results from tournaments, to their own blogs, with fairly minimal code.

How it works

When enabling the tournament_services module, it installs a services endpoint
(http://drupal.stackexchange.com/questions/4718/how-to-create-test-endpoint) that automatically creates a path on the hosting site under http://example.com/tournament. This provides a base URL from which each service will derive from. Authentication to use the service URLs requires, at the least, an account on the hosting site.

Authentication

You must have a drupal user account on the site hosting the exposed API, and you'll need to use it to access the data from the services. This will require making two requests, the first of which authenticates the user, and the second, uses the authenticated response (session data) to retrieve results from the service.

Exposed services

1) Tournament Details - returns basic details about tournament. It essentially returns the node object, so it contains information like title, start date, size, participant type.

Seeking details on a tournament with node id of 13 at site http://example.com
URL: http://example.com/tournament/tournament_details/13

Additional notes: This implements the "retrieve" operation on the rest server defined in the .install file.

2) Tournament Participants - returns participant list of a given tournament.

Seeking a participant list for tournament with nid of 76 at site http://example.com
URL: http://example.com/tournament/tournament_participants/76

Additional notes: This implements the "retrieve" operation on the rest server defined in the .install file.

3) Tournament Match List - returns match list given a tournament.

Seeking a match list of active (i.e. not finished) matches on tournament with nid of 412 at site http://example.com
URL: http://example.com/tournament/tournament_match_list?tid=412&status=active

Seeking a match list of finished (i.e. not active) matches on tournament 478 at site http://example.com
URL: http://example.com/tournament/tournament_match_list?tid=478&status=finished

Additional notes: Only "active" and "finished" are allowed statuses, all other strings will fail. This implements the "index" operation on the rest server defined in the .install file. The format here is a little different, using GET parameters as mandated by the REST server implemenation.

Client code examples

Before testing if your client code is working, ensure that you can access the service URL you seek to consume via a browser. First, login to the site directly, and ensure you're getting proper output when accessing the URL directly in the browser. This will confirm that the service is set up properly on the host end. The client code is slightly trickier, so you'll definitely want to first confirm the hosting site is exposing the service properly. Once you've done that, you can write your example code.

1) Example of client code for accessing tournament details from within a drupal site (i.e. using drupal api functions to do the service call and parse the response).

// Based off http://drupal.org/node/910598

// Here's the site URL + the services endpoint (tournament)
$base_url = 'http://example.com/tournament';

// Login (user and pass for the authenticating user)
$data = array(
  'username' => 'admin',
  'password' => 'p4$$w()rD',
);
$data = http_build_query($data, '', '&');

$headers = array();
$options = array(
  'headers' => array(
    'Accept' => 'application/json',
  ),
  'method' => 'POST',
  'data' => $data
);

$response = drupal_http_request($base_url . '/user/login', $options);
$resp_data = json_decode($response->data);

if ($resp_data != null) {
  // Now recycle the login cookie we recieved in the first request
  $options['headers']['Cookie'] = $resp_data->session_name . '=' . $resp_data->sessid;

  // Get info about a user
  $data = array();
  $options['data'] = http_build_query($data, '', '&');
  $options['method'] = 'GET';
  // An example of requesting the tournament details service for tournament with node id of 13
  $response = drupal_http_request($base_url . '/tournament/tournament_details/13', $options);
  exit(print_r($response,TRUE));

}else{
  exit($response->error);
}

2) Example of drupal independent client code (PHP) using cURL to access the same URL:

// This can be run from the command line, or opened in a browser.  It's drupal independent.

// Must have user login service exposed.  It IS possible the hosting site will have a different endpoint for this
// other than 'tournament'.  They will need to provide you with the proper URL (endpoint) if that's the case.
$service_url = 'http://example.com/tournament/user/login.xml'; // .xml asks for xml data in response
$post_data = array(
  'username' => 'admin',
  'password' => 'a',
);
$post_data = http_build_query($post_data, '', '&'); // Format post data as application/x-www-form-urlencoded

// set up the request
$curl = curl_init($service_url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);  // have curl_exec return a string

curl_setopt($curl, CURLOPT_POST, true);             // do a POST
curl_setopt($curl, CURLOPT_POSTFIELDS, $post_data); // POST this data

// make the request
curl_setopt($curl, CURLOPT_VERBOSE, true); // output to command line
$response = curl_exec($curl);
curl_close($curl);
print "RESPONSE:\n";
var_dump($response);

// parse the response
$xml = new SimpleXMLElement($response);
$session_cookie = $xml->session_name .'='. $xml->sessid;


$service_url = 'http://example.com/tournament/tournament_details/13'; // .xml asks for xml data in response, .json can be used as well

// set up the request
$curl = curl_init($service_url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);  // have curl_exec return a string

curl_setopt($curl, CURLOPT_COOKIE, "$session_cookie"); // use the previously saved session

// make the request
curl_setopt($curl, CURLOPT_VERBOSE, true); // output to command line
$response = curl_exec($curl);
curl_close($curl);
print "RESPONSE:\n";
var_dump($response);

Help/troubleshooting

The best way to start working with the services exposed by a site with the tournament_services module enabled, is to login to the site via a web browser, and try to access the particular service URL. You will get the json, xml, or whatever output you may have chosen directly in the browser window, since you will pass the authentication step. You can also confirm the services are NOT working for anonymous users, by logging out and attempting to access the same URL. If you are still having difficulty at this point, and you're sure of the URL, you should then contact the site administrator, as the issue may lie on her end.