Am I the only person finding Services to be very poorly documented? I can't find just basic information about callback arguments or anything, I've spent the last 40 minutes just trying to find out the correct arguments to accept in my custom service and I still haven't found an answer.
It says services 2 is no longer supported because services 3 is out, but almost every example I find is not compatible with services 3 and all links to documentation for version 3 say things along the lines of "we'll be adding information here'. The API Key authentication has just gone and I can't even find a reference to it. Half of the code examples have no comments in them whatsoever
I got into drupal because it is famously good with documentation, but the services module is proving to be a massive pain in my a**e
Comments
If you would like to see what
If you would like to see what arguments expected for each of the calls, please take a look at tests of the resources.
Or please ask your specific question here.
Tests of the resources? You
Tests of the resources? You mean examples? They are not exhaustive.
I'd like to know what the arguments that are available are so I can make sure I am selecting the right one. I also want to know what each of the '#return' values are available so I can select the right one. I'd like to just find a reference, so I'm not plucking words out of the ether hoping they are correct
If you would like to see
If you would like to see simply list of arguments for resources please check them in the code http://drupalcode.org/project/services.git/tree/refs/heads/7.x-3.x:/reso...
For practical example I proposed to look at tests in services module (i.e. tests/functional folder). For example: http://drupalcode.org/project/services.git/blob/refs/heads/7.x-3.x:/test... this is how to prepare node array for creating new node.
Consider services 2 ...
I've been using services 2 for over 2 years and they are very stable. While they have some quirks (e.g., format for received node taxonomy items is different from that expected by the node save method), you can Google your way through most of them.
I've been following services 3 and while I have no doubt they are superior in principle and hope to migrate at some point, my impression is that they might not yet be as stable as services 2. I'd certainly recommend trying to get up and running with services 3, as that's the supported version, but I for one am not ready yet to transition into it, and if you get frustrated with services 3, perhaps it's worthwhile trying services 2. Just know that you'll need to migrate in the not too distant future, but that might be a trade-off that works for you.
It's unfortunate and surprising that services 2 is not supported anymore, as I suspect there are thousands of sites currently using it in production who are not ready or able to move to services 3 yet.
If you're using Flex, a good services 2 tutorial is here: http://electricpineapple.net/2009/03/10/api-keys-to-the-city-setting-up-...
Good luck,
Micah
Thanks Waldma, but I am not
Thanks Waldmann, but I am not using Flex.
Ygerasimov, that is precisely my point. An uncommented and complex script is not documentation. I've got my script working, but some things I did because I saw in examples and have no idea what they are for, this doesn't help my development and I don't believe I am alone. I apprecaite that maybe services is more an intermediate subject, but that doesn't mean it should be complete guesswork.
I even bought a book called 'drupal webservices' and sent it back because it didn't even mention anything whatsoever about outgoing requests. 'Pro Drupal Development' also just gives brief and simple examples of drupal code with no explanation of why things go in certain places. It's incredibly disheartening to find such poorly maintained documentation when people harp on about how well supported the platform is.
Dear mykmallett, thank you
Dear mykmallett, thank you very much for pointing out poor state of documentation. I will put it to agenda of maintainers and will ask you to review when it is done. Main source of documentation should be handbook http://drupal.org/node/736522
And your first contribution...
@mykmallett - welcome to the OpenSource world. I'd suggest you take your new found knowledge and share it with the community. I hope this is really the core of your point. You've found a lack of documentation, struggled to find a solution but found success. Now is the time for you to contribute to the community. "ygerasimov" has even offered to ease you into the handbook process. Looks like a good day for Drupal :)
You have to look in the code
@mykmallett,
See the source file "services.services.api.php" and see if that helps you.
Some working examples
I've put some working example modules here: http://www.blakesenftner.com/Services-3-examples
Drupal 7 hook_permission()
Nice example. I tried the Drupal 7 version and I discovered the hook_perm() in the existing code.
Of course, in drupal 7 this is hook_permission. And the format changed.
Here is the code that I modified (file: api_shell.module):
/**************************************************************************************************** Implementation of hook_permission().
* @see http://api.drupal.org/api/function/hook_perm/6
* @return An array of the valid permission names for this module
*/
function api_shell_permission() {
return array(
'api shell create' => array(
'title' => t('API shell create'),
),
'api shell view any' => array(
'title' => t('API shell view any'),
),
'api shell view own' => array(
'title' => t('API shell view own'),
),
'api shell edit any' => array(
'title' => t('API shell edit any'),
),
'api shell edit own' => array(
'title' => t('API shell edit own'),
),
'api shell delete any' => array(
'title' => t('API shell delete any'),
),
'api shell delete own' => array(
'title' => t('API shell delete own'),
),
);
}