How do I use API versioning?

Question

I'm using the Services module to produce a REST API. According to the official documentation, there is a way to version services resources. I believe version here means supplying a single API (e.g. example.com/api) and allowing clients to specify which version they want per resource with headers.

So I think that means that these two requests would return different results, despite living at the same URL:

Version 1.0:

POST /api/v1/system/set_variable HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json

Version 1.2:

POST /api/v1/system/set_variable HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json
services_system_set_variable_version: 1.2

I cannot make this work for the life of me. Here are the steps I took:

1. Enabled the system/set_variable service

2. Added the following code to mymodule.module (cribbed directly from services.versions.api.php)

.

function _system_resource_set_variable_update_1_1() {
  $new_set = array(
    'help' => 'Create a node with an nid test',
  );
  return $new_set;
}

function _system_resource_set_variable_update_1_2() {
  $new_set = array(
    'help' => 'Create a node with an nid optional prams.',
    'args' => array(
      array(
        'name' => 'name',
        'optional' => TRUE,
        'source' => array('data' => 'name'),
        'description' => t('The name of the variable to set.'),
        'type' => 'string',
      ),
      array(
        'name' => 'value',
        'optional' => TRUE,
        'source' => array('data' => 'value'),
        'description' => t('The value to set.'),
        'type' => 'string',
      ),
    ),
  );
  return $new_set;
}

3. Cleared cache
4. Attempted to use the system/set_variable service with postman.

5. Saw that the system/set_variable service was working

6. Attempted to use the system/set_variable service without arguments, per _system_resource_set_variable_update_1_2

7. Saw that arguments were still required

So what am I doing wrong here? I'm pretty sure I followed all the instructions.

Answer 1

Quote from services.versions.api.php

For clients that want to request a specific version they need to pass a certain header

• services_RESOURCE_METHOD_version = version
• as an example, services_system_set_variable_version = 1.2
• @see ServicesVersionTests for code examples

Make sure to use set acceptable Content-Type.

Content-Type: application/x-www-form-urlencoded

GET /v1/status HTTP/1.1
Content-Type: application/x-www-form-urlencoded
API-KEY: AAAAAAA
TOKEN: VVVVVVV
services_status_index_version: 1.1
Host: local.mywebsite.com
Connection: close
User-Agent: Paw/3.0.16 (Macintosh; OS X/10.11.6) GCDHTTPRequest