From a5df922306bbb756c347a89e4016d370150bf715 Mon Sep 17 00:00:00 2001
From: Bernhard Posselt <nukeawhale@gmail.com>
Date: Thu, 2 May 2013 16:11:11 +0200
Subject: [PATCH] more infos about external api

---
 developer_manual/app/app/externalapi.rst | 59 ++++++++++++++++++++++--
 1 file changed, 55 insertions(+), 4 deletions(-)

diff --git a/developer_manual/app/app/externalapi.rst b/developer_manual/app/app/externalapi.rst
index 9b6be8e53..7bb083164 100644
--- a/developer_manual/app/app/externalapi.rst
+++ b/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
+        }
+      }
+    }
+