more infos about external api

developer_manual/app/app/externalapi.rst

@@ -20,11 +20,13 @@ Methods are registered inside the :file:`appinfo/routes.php` using :php:class:`O
 
   <?php
 
-  OCP\API::register(
+  \OCP\API::register(
       'get', 
-      '/cloud/users', 
-      array('OC_Provisioning_API_Users', 'getUsers'), 
-      'provisioning_api', 
+      '/apps/yourapp/url', 
+      function($urlParameters) {
+      	return new \OC_OCS_Result($data);
+      }
+      'yourapp', 
       OC_API::ADMIN_AUTH
   );
 
@@ -33,3 +35,52 @@ Returning Data
 Once the API backend has matched your URL, your callable function as defined in
 **$action** will be executed. This method is passed as array of parameters that you defined in **$url**. To return data back the the client, you should return an instance of :php:class:`OC_OCS_Result`. The API backend will then use this to construct the XML or JSON response.
 
+Authentication & Basics
+~~~~~~~~~~~~~~~~~~~~~~~
+Because REST is stateless you have to send user and password each time you access the API. Therefore running ownCloud **with SSL is highly recommended** otherwise **everyone in your network can log your credentials**::
+
+    https://user:password@yourowncloud.com/ocs/v1.php/apps/yourapp
+
+
+Output
+~~~~~~
+The output defaults to XML. If you want to get JSON append this to the URL::
+    
+    ?format=json
+
+Output from the application is wrapped inside a **data** element:
+
+**XML**:
+
+.. code-block:: xml
+
+    <?xml version="1.0"?>
+    <ocs>
+     <meta>
+      <status>ok</status>
+      <statuscode>100</statuscode>
+      <message/>
+     </meta>
+     <data>
+       <!-- data here -->
+     </data>
+    </ocs>
+
+
+**JSON**:
+
+.. code-block:: js
+
+    {
+      "ocs": {
+        "meta": {
+          "status": "ok",
+          "statuscode": 100,
+          "message": null
+        },
+        "data": {
+          // data here
+        }
+      }
+    }
+