services.services.api.php

   1 <?php
   2
   3 /**
   4  * @file
   5  * Hooks provided by Services for the definition of new services.
   6  */
   7
   8 /**
   9  * @addtogroup hooks
  10  */
  11
  12  /**
  13   * Defines function signatures for resources available to services.
  14   *
  15   * Functionally this is very similar to the way hook_menu() works, and in many
  16   * ways Services can be seen as an abstraction layer on top of hook_menu().
  17   *
  18   * @return
  19   *   An associative array which defines available resources.
  20   *
  21   *   The associative array which defines services has five possible top
  22   *   level keys. The operations array has five possible keys representing
  23   *   the CRUD operations.
  24   *
  25   *     - #api_version
  26   *     - operations
  27   *       - create
  28   *       - retrieve
  29   *       - update
  30   *       - delete
  31   *       - index
  32   *     - actions
  33   *     - targeted_actions
  34   *     - relationships
  35   *
  36   *   The #api_version is the services resource API that the resource is written
  37   *   for. This makes it possible for services to upgrade resource declarations
  38   *   if the format changes. See services_resource_api_version_info(). If no
  39   *   version is given then 3001 is assumed. Which is the format used before the
  40   *   versioning was introduced.
  41   *
  42   *   The CRUD functions in 'operations' are pretty self-explanatory. Index is
  43   *   an extra CRUD-type function that allows you to create pageable lists.
  44   *
  45   *   Actions are performed directly on the resource type, not a individual
  46   *   resource. The following example is hypothetical (but plausible). Say
  47   *   that you want to expose a API for the apachesolr module. One of the
  48   *   things that could be exposed is the functionality to reindex the whole
  49   *   site at apachesolr/reindex.
  50   *
  51   *   Targeted actions acts on a individual resource. A good, but again -
  52   *   hypothetical, example would be the publishing and unpublishing of nodes
  53   *   at node/123/publish.
  54   *
  55   *   Relationship requests are convenience methods (sugar) to get something
  56   *   thats related to a individual resource. A real example would be the
  57   *   ability to get the files for a node at node/123/files.
  58   *
  59   *   The first five (the CRUD functions + index) define the indvidual service
  60   *   callbacks for each function. However 'actions', 'targeted_actions',
  61   *   and 'relationships' can contain multiple callbacks.
  62   *
  63   *   For those familiar with Services 2.x, these callbacks are created
  64   *   similarly, but the keys have changed around a bit. The following keys
  65   *   are used to describe a callback.
  66   *
  67   *   - help: Text describing what this callback does.
  68   *   - callback: The name of a function to call when this resource is
  69   *     requested.
  70   *   - file: an array describing the file which contains the callback
  71   *     function
  72   *   - access callback: The name of a function to call to check whether
  73   *     the requesting user has permission to access this resource. If not
  74   *     specified, this defaults to 'user_access'.
  75   *   - access callback file: an array describing the file which contains the
  76   *     access callback function.  This attribute only needs to be supplied if
  77   *     the method callback and the access callback are defined in different
  78   *     files, for example when a method callback is overridden using
  79   *     hook_services_resources_alter but the access callback is not
  80   *   - access arguments: The arguments to pass to the access callback.
  81   *   - access arguments append: A boolean indicating whether the resource's
  82   *     arguments should be appended to the access arguments. This can be useful
  83   *     in situations where an access callback is specific to the particular
  84   *     item ('edit all nodes' vs 'edit my nodes'). Defaults to FALSE.
  85   *   - args: an array describing the arguments which should be passed to this
  86   *     resource when it is called. Each element in the array is an associative
  87   *     array containing the following keys:
  88   *
  89   *     - name: The name of this argument.
  90   *     - type: The data type of this argument (int, string, array)
  91   *     - description: Text describing this argument's usage.
  92   *     - optional: A boolean indicating whether or not this argument is optional.
  93   *     - source: Where this argument should be retrieved from. This can be
  94   *       'data' (indicating the POST data), 'param' (indicating the query
  95   *       string) or 'path' (indicating the url path). In the case of path,
  96   *       an additional parameter must be passed indicating the index to be used.
  97   *     - default value: this is a value that will be passed to the method for
  98   *       this particular argument if no argument value is passed
  99   *
 100   *   A detailed example of creating a new resource can be found at
 101   *   http://drupal.org/node/783460 and more information about how
 102   *   REST resources are managed can be found at http://drupal.org/node/783254.
 103   */
 104 function hook_services_resources() {
 105   $node_resource = array(
 106     'node' => array(
 107       'retrieve' => array(
 108         'file' => array('type' => 'inc', 'module' => 'services', 'name' => 'resources/node_resource'),
 109         'callback' => '_node_resource_retrieve',
 110         'args' => array(
 111           array(
 112             'name' => 'nid',
 113             'optional' => FALSE,
 114             'source' => array('path' => 0),
 115             'type' => 'int',
 116             'description' => 'The nid of the node to get',
 117           ),
 118         ),
 119         'access callback' => '_node_resource_access',
 120         'access callback file' => array('type' => 'inc', 'module' => 'services', 'name' => 'resources/node_resource'),
 121         'access arguments' => array('view'),
 122         'access arguments append' => TRUE,
 123       ),
 124       'create' => array(
 125         'file' => array('type' => 'inc', 'module' => 'services', 'name' => 'resources/node_resource'),
 126         'callback' => '_node_resource_create',
 127         'args' => array(
 128           array(
 129             'name' => 'node',
 130             'optional' => FALSE,
 131             'source' => 'data',
 132             'description' => 'The node data to create',
 133             'type' => 'array',
 134           ),
 135         ),
 136         'access callback' => '_node_resource_access',
 137         'access arguments' => array('create'),
 138         'access arguments append' => TRUE,
 139       ),
 140       'update' => array(
 141         'file' => array('type' => 'inc', 'module' => 'services', 'name' => 'resources/node_resource'),
 142         'callback' => '_node_resource_update',
 143         'args' => array(
 144           array(
 145             'name' => 'nid',
 146             'optional' => FALSE,
 147             'source' => array('path' => 0),
 148             'type' => 'int',
 149             'description' => 'The nid of the node to get',
 150           ),
 151           array(
 152             'name' => 'node',
 153             'optional' => FALSE,
 154             'source' => 'data',
 155             'description' => 'The node data to update',
 156             'type' => 'array',
 157           ),
 158         ),
 159         'access callback' => '_node_resource_access',
 160         'access arguments' => array('update'),
 161         'access arguments append' => TRUE,
 162       ),
 163       'delete' => array(
 164         'file' => array('type' => 'inc', 'module' => 'services', 'name' => 'resources/node_resource'),
 165         'callback' => '_node_resource_delete',
 166         'args' => array(
 167           array(
 168             'name' => 'nid',
 169             'optional' => FALSE,
 170             'source' => array('path' => 0),
 171             'type' => 'int',
 172           ),
 173         ),
 174         'access callback' => '_node_resource_access',
 175         'access arguments' => array('delete'),
 176         'access arguments append' => TRUE,
 177       ),
 178       'index' => array(
 179         'file' => array('type' => 'inc', 'module' => 'services', 'name' => 'resources/node_resource'),
 180         'callback' => '_node_resource_index',
 181         'args' => array(
 182           array(
 183             'name' => 'page',
 184             'optional' => TRUE,
 185             'type' => 'int',
 186             'description' => 'The zero-based index of the page to get, defaults to 0.',
 187             'default value' => 0,
 188             'source' => array('param' => 'page'),
 189           ),
 190           array(
 191             'name' => 'fields',
 192             'optional' => TRUE,
 193             'type' => 'string',
 194             'description' => 'The fields to get.',
 195             'default value' => '*',
 196             'source' => array('param' => 'fields'),
 197           ),
 198           array(
 199             'name' => 'parameters',
 200             'optional' => TRUE,
 201             'type' => 'array',
 202             'description' => 'Parameters array',
 203             'default value' => array(),
 204             'source' => array('param' => 'parameters'),
 205           ),
 206         ),
 207         'access arguments' => array('access content'),
 208       ),
 209       'relationships' => array(
 210         'files' => array(
 211           'file' => array('type' => 'inc', 'module' => 'services', 'name' => 'resources/node_resource'),
 212           'help'   => t('This method returns files associated with a node.'),
 213           'access callback' => '_node_resource_access',
 214           'access arguments' => array('view'),
 215           'access arguments append' => TRUE,
 216           'callback' => '_node_resource_load_node_files',
 217           'args'     => array(
 218             array(
 219               'name' => 'nid',
 220               'optional' => FALSE,
 221               'source' => array('path' => 0),
 222               'type' => 'int',
 223               'description' => 'The nid of the node whose files we are getting',
 224             ),
 225             array(
 226               'name' => 'file_contents',
 227               'type' => 'int',
 228               'description'  => t('To return file contents or not.'),
 229               'source' => array('path' => 2),
 230               'optional' => TRUE,
 231               'default value' => TRUE,
 232             ),
 233           ),
 234         ),
 235       ),
 236     ),
 237   );
 238   if (module_exists('comment')) {
 239     $comments = array(
 240       'file'                    => array('type' => 'inc', 'module' => 'services', 'name' => 'resources/node_resource'),
 241       'help'                    => t('This method returns the number of new comments on a given node.'),
 242       'access callback'         => 'user_access',
 243       'access arguments'        => array('access comments'),
 244       'access arguments append' => FALSE,
 245       'callback'                => '_node_resource_load_node_comments',
 246       'args'                    => array(
 247         array(
 248           'name'         => 'nid',
 249           'type'         => 'int',
 250           'description'  => t('The node id to load comments for.'),
 251           'source'       => array('path' => 0),
 252           'optional'     => FALSE,
 253         ),
 254         array(
 255           'name'         => 'count',
 256           'type'         => 'int',
 257           'description'  => t('Number of comments to load.'),
 258           'source'       => array('param' => 'count'),
 259           'optional'     => TRUE,
 260         ),
 261         array(
 262           'name'         => 'offset',
 263           'type'         => 'int',
 264           'description'  => t('If count is set to non-zero value, you can pass also non-zero value for start. For example to get comments from 5 to 15, pass count=10 and start=5.'),
 265           'source'       => array('param' => 'offset'),
 266           'optional'     => TRUE,
 267         ),
 268       ),
 269     );
 270     $node_resource['node']['relationships']['comments'] =  $comments;
 271   }
 272   return $node_resource;
 273 }