Permalink
Browse files

docs(web_services): document the use of parameters in method declarat…

…ions

Adds some info on conventions used for documenting method parameters
  • Loading branch information...
hypeJunction committed Jun 27, 2015
1 parent d47fc5e commit 750e31b988131c53a90be987daa33229b1573f75
Showing with 42 additions and 0 deletions.
  1. +42 −0 docs/guides/web-services.rst
@@ -89,6 +89,48 @@ by default: xml, json, and serialized php. You can request the different
formats for substituting “json” or “php” for “xml” in the above URLs.
You can also add additional response formats by defining new viewtypes.
+Parameters
+~~~~~~~~~~
+
+Parameters expected by each method should be listed as an associative array, where the key represents the parameter name, and the value contains an array with ``type``, ``default`` and ``required`` fields.
+
+Values submitted with the API request for each parameter should match the declared type. API will throw on exception if validation fails.
+
+Recognized parameter types are:
+
+ - ``integer`` (or ``int``)
+ - ``boolean`` (or ``bool``)
+ - ``string``
+ - ``float``
+ - ``array``
+
+Unrecognized types will throw an API exception.
+
+You can use additional fields to describe your parameter, e.g. ``description``.
+
+.. code:: php
+
+ elgg_ws_expose_function('test.greet',
+ 'my_greeting',
+ array(
+ 'name' => array(
+ 'type' => 'string',
+ 'required' => true,
+ 'description' => 'Name of the person to be greeted by the API',
+ ),
+ 'greeting' => array(
+ 'type' => 'string',
+ 'required' => false,
+ 'default' => 'Hello',
+ 'description' => 'Greeting to be used, e.g. "Good day" or "Hi"',
+ ),
+ ),
+ 'A testing method which greets the user with a custom greeting',
+ 'GET',
+ false,
+ false
+ );
+
API authentication
------------------

0 comments on commit 750e31b

Please sign in to comment.