Drupal services documentation: what I pieced together

The services module has been much over-hyped and under documented, considering how hard it is to use. Version 3, we are assured, will be much better, but at the moment rest_server and soap_server don't appear to work. So right now we're between a rock and a hard place. But this post should help you to move forward.

Service and 'resources'

I supposed that I should use hook_service to define services as in the node_service module. However it turns out that there is another, similar but completely undocumented option, as epitomised in the node_resource module. This implements hook_service_resource, and from what I can gather, is the way forward.

First of all the module does not work unless you choose an authentication method. It will return Not Authorised for everything. This may be a rather over-zealous default. By flipping the return TRUE to FALSE at the end of services_auth_invoke() in services.module the module should work without your choosing an authentication method.

Key authentication

We shall be working with the key authentication method with 'Use Keys' checked and 'Use sessid' not checked. So go ahead and generate a key.

When you check 'Use keys' you are requiring four new arguments to be prepended to your main arguments. The first argument is a hash and the others are some of the components of the hash.

So you need to write a function to generate the hash. The services_keyauth.module has it's own function to make a matching hash called services_get_hash(); Note that the api_key must be known to the system already, and that the hash is then valid for one instance of one method call.

hash_hmac("sha256", $timestamp.';'.$domain_name.';'.$nonce.';'.$method_name)), $api_key);
echo hash_hmac("sha256", "1292321664;dev.matslats.net;123;currency_resource.retrieve", e70bd8c6791640ba773ce62e98dd3be6);
<< 099e6d950892ab517da116b0e2fca0480596bdaf30157766b7d2f239bed9e59

The services module recreates the hash at the other end, looking up the key from the domain name, and if the hashes match, the request is authenticated. Its a pretty solid process.

The REST server

So now we are ready to call the function. The simplest way to get a result is to use the rest_server module, and to call via GET, which is to say, using the url alone

https://domain.com/service/rest/$resource/$hash/$domain_name/$timestamp/$nonce/$arg1/$arg2...
http://dev.matslats.netservices/rest/currency_resource/d099e6d950892ab517da116b0e2fca0480596bdaf30157766b7d2f239bed9e59/dev.matslats.net/1292321664/123/524

I regret to say, this doesn't work. It seems that the REST server does not anticipate those extra authentication arguments...