Merge pull request #8608 from hypeJunction/ws-docs-1-11

Security and parameters documentation for web services

docs/guides/web-services.rst

@@ -23,6 +23,21 @@ available on your site. This will also be covered.
    :local:
    :depth: 2
 
+Security
+--------
+
+It is crucial that the web services are consumed via secure protocols. Do not
+enable web services if your site is not served via HTTPs. This is especially
+important if you allow API key only authentication.
+
+If you are using third-party tools that expose API methods, make sure to carry
+out a thorough security audit. You may want to make sure that API authentication
+is required for ALL methods, even if they require user authentication. Methods that
+do not require API authentication can be easily abused to spam your site.
+
+Ensure that the validity of API keys is limited and provide mechanisms for your
+API clients to renew their keys.
+
 Exposing methods
 ----------------
 
@@ -74,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
 ------------------