Currently in services module a service method is declared like this:

array(
      '#method'           => 'user.delete',
      '#callback'         => 'user_service_delete',
      '#access callback'  => 'user_service_delete_access',
      '#file'             => array('file' => 'inc', 'module' => 'user_service'),
      '#args'             => array(
        array(
          '#name'           => 'uid',
          '#type'           => 'int',
          '#description'    => t('User ID.'),
        ),
      ),
      '#return'           => 'struct',
      '#help'             => t('Delete an user.')
    ),

However, this is a pretty big break from the Drupal coding style. Generally, names are declared as keys of the array, not as elements in that array. For instance:


// Forms API
$form['elementname'] = array(
);

// Schema API
$schema['tablename'] = array(
);

// Menu Item Definition
$item['pathname'] = array(
);

So I propose two things:

  1. Method names be declared as keys instead of as a separate attribute (removing #method).
  2. Argument names be declared as keys instead of as a separate attribute (removing #name).

The end result would look like this:

$service['user.delete'] = array( // Remove #method
      '#callback'         => 'user_service_delete',
      '#access callback'  => 'user_service_delete_access',
      '#file'             => array('file' => 'inc', 'module' => 'user_service'),
      '#args'             => array(
        'uid' => ( // Remove #name
          '#type'           => 'int',
          '#description'    => t('User ID.'),
        ),
      ),
      '#return'           => 'struct',
      '#help'             => t('Delete an user.')
    );

This has several advantages:

  1. Removes two properties which would otherwise have to be remembered
  2. Places it into line with other similar Drupal declaration formats, thus making it easier for developers to start making services.
  3. Allows separate methods to be readily identified through whitespace separation and clearer syntax highlighting.

I thinking making this relatively simple change would ease the transition from general Drupal development to making full blown web services through services module.

Comments

theflowimmemorial’s picture

A prime example of why not to do these things at 2 in the morning. The proposed syntax, with corrections is below.

$service['user.delete'] = array( // Remove #method
      '#callback'         => 'user_service_delete',
      '#access callback'  => 'user_service_delete_access',
      '#file'             => array('file' => 'inc', 'module' => 'user_service'),
      '#args'             => array(
        'uid' =>  array( // Remove #name
          '#type'           => 'int',
          '#description'    => t('User ID.'),
        ),
      ),
      '#return'           => 'struct',
      '#help'             => t('Delete an user.')
    );
marcingy’s picture

Priority: Normal » Minor

The issue of naming conventions etc are currently up for discussion. If we are considering this change we should likely look whether we should remove # at the same time.

theflowimmemorial’s picture

Regarding removing the #, that is probably yes. They exist in the Forms API because form elements can be nested inside other form elements. So the # is needed to distinguish between properties of the form and other form elements. However, it does not seem like it would be necessary within this unless services.module supports having nested API functions which may be useful for retrieving comments or other dependent resources. Either way, the decision should be based on the functionality which the API provides.

gdd’s picture

Status: Active » Postponed

So the hashmarks got fixed in #616490: Services API misuses hash/number (#) symbols and the rest won't make it into this version. Not sure what will happen in a future 3.x, marking as postponed for future consideration.

marcingy’s picture

Version: 6.x-1.x-dev » 6.x-3.x-dev

Bumping version - moved to 3.x as this is a major API change.

gdd’s picture

Priority: Minor » Normal
Status: Postponed » Active

The change to method naming has been done in 3.x already, which is great. I agree with the idea of removing name and instead making args a keyed array. This will hopefully make the calling code a little cleaner.

kylebrowning’s picture

Status: Active » Closed (fixed)

This has been done in 3.x