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:
- Method names be declared as keys instead of as a separate attribute (removing #method).
- 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:
- Removes two properties which would otherwise have to be remembered
- Places it into line with other similar Drupal declaration formats, thus making it easier for developers to start making services.
- 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
Comment #1
theflowimmemorial commentedA prime example of why not to do these things at 2 in the morning. The proposed syntax, with corrections is below.
Comment #2
marcingy commentedThe 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.
Comment #3
theflowimmemorial commentedRegarding 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.
Comment #4
gddSo 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.
Comment #5
marcingy commentedBumping version - moved to 3.x as this is a major API change.
Comment #6
gddThe 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.
Comment #7
kylebrowning commentedThis has been done in 3.x