How to create a custom resource with Services-3.x

Question

Drupal 7.9

I have installed Services 3.x module and can successfully access nodes etc using the rest server e.g. http://api.domain.com/api/rest/node/6.xml. I now wish to create a custom resource and am having difficulty understanding how to do that correctly. I have followed the much-quoted tutorials on this which all seem to be based on the same example: http://drupal.org/node/783460 and am struggling to understand hook_services_resources. For example:

   'note' => array(
     'retrieve' => array(
       'help' => 'Retrieves a note',
       'file' => array('file' => 'inc', 'module' => 'noteresource'),
       'callback' => '_noteresource_retrieve',
       'access callback' => '_noteresource_access',
       'access arguments' => array('view'),
       'access arguments append' => TRUE,
       'args' => array(
         array(
           'name' => 'id',
           'type' => 'int',
           'description' => 'The id of the note to get',
           'source' => array('path' => '0'),
           'optional' => FALSE,
         ),
       ),
     ),

Where are the available values for these arrays? For example what are the valid options for source in the args array? I've seen the following: array('path' => '0'), 'data', array('param' => 'page'), 'param'. Where can I find a reference for how this needs to be defined?

To give a bit more information about what I want to achieve, we have a custom form that accepts a series of parameters and returns a set of html-formatted data. The form calls this function: return account_manager_search_accounts($billing_party, $other_party, $date_from, $date_to, $billing_id); }

My idea is to allow users to retrieve the appropriately formatted data (e.g. json, xml) RESTfully and it seemed Services was the right way to do that.

Something like:

function account_manager_services_resources() {
  return array(
   'records' => array(
     'retrieve' => array(
       'help' => 'Retrieves records',
       'file' => array('file' => 'inc', 'module' => 'account_manager'),
       'callback' => '_account_manager_records_retrieve',
       'access callback' => 'user_access',
       'access arguments' => array('view records'),
       'access arguments append' => TRUE,
       'args' => array(
         array(
           'name' => 'billing_party',
           'type' => 'varchar',
           'description' => 'The billing party',
           'source' => what should go here,
           'optional' => FALSE,
         ),
         array(
           'name' => 'other_party',
           'type' => 'int',
           'description' => 'The other party',
           'source' => what should go here,
           'optional' => FALSE,
         ),
       ),
     ),
   ),
  );
}

Then I'm not even sure what the URL would be for this. Would it be something like: ./api/rest/account_manager/records

Any suggestions or advice appreciated.

Answer 1

All the documentation for the hook is in the services.services.api.php file included with the module. The args array is:

an array describing the arguments which should be passed to this resource when it is called. Each element in the array is an associative array containing the following keys:

• name: The name of this argument.
• type: The data type of this argument (int, string, array)
• description: Text describing this argument's usage.
• optional: A boolean indicating whether or not this argument is optional.
• source: Where this argument should be retrieved from. This can be 'data' (indicating the POST data), 'param' (indicating the query string) or 'path' (indicating the url path). In the case of path, an additional parameter must be passed indicating the index to be used.
• default value: this is a value that will be passed to the method for this particular argument if no argument value is passed

There are a fair few examples in that file it might be worth giving them a read through, although the API documentation does actually specifically refer to the link you posted above as a detailed example of creating a new resource.

Answer 2

If you look at services.services.api.php It looks like this.

https://gist.github.com/1b4a1bdef433cad8b142