[Pkg-owncloud-commits] [owncloud-doc] 53/270: add chapter about restful api and cors

[David Prévot]

This is an automated email from the git hooks/post-receive script.

taffit pushed a commit to branch master
in repository owncloud-doc.

commit 4a013ada2c60599ccbbe49129df3ca2c51c49f28
Author: Bernhard Posselt <dev at bernhard-posselt.com>
Date:   Sat May 10 12:15:14 2014 +0200

    add chapter about restful api and cors
---
 developer_manual/app/api.rst | 77 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 76 insertions(+), 1 deletion(-)

diff --git a/developer_manual/app/api.rst b/developer_manual/app/api.rst
index 942e609..7d03502 100644
--- a/developer_manual/app/api.rst
+++ b/developer_manual/app/api.rst
@@ -1,4 +1,79 @@
+===========
 RESTful API
 ===========
 
-.. sectionauthor:: Bernhard Posselt <dev at bernhard-posselt.com>
\ No newline at end of file
+.. sectionauthor:: Bernhard Posselt <dev at bernhard-posselt.com>
+
+Offering a RESTful API is not different from creating a :doc:`route <routes>` and :doc:`controllers <controllers>` for the webinterface. It is recommended though to inherit from ApiController and add **@CORS** annotations to the methods so that `also web applications will be able to access the API <https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS>`_.
+
+.. code-block:: php
+
+    <?php
+    namespace OCA\MyApp\Controller;
+
+    use \OCP\AppFramework\ApiController;
+    use \OCP\IRequest;
+
+    class AuthorApiController extends ApiController {
+
+        public function __construct($appName, IRequest $request) {
+            parent::__construct($appName, $request);
+        }
+
+        /**
+         * @CORS
+         */
+        public function index() {
+
+        }
+
+    }
+
+CORS also needs a seperate url for the preflighted **OPTIONS** request that easily be added by adding the following route:
+
+.. code-block:: php
+
+    <?php
+    // appinfo/routes.php
+    array(
+        'name' => 'author_api#preflighted_cors', 
+        'url' => '/api/1.0/authors/{path}', 
+        'verb' => 'OPTIONS', 
+        'requirements' => array('path' => '.+')
+    )
+
+
+Keep in mind that multiple apps will likely depend on the API interface once it is published and they will move at different speeds to react on changes implemented in the API. Therefore it is recommended to version the API in the URL to not break existing apps when backwards incompatible changes are introduced::
+
+    /index.php/apps/myapp/api/1.0/resource
+
+Modifying the CORS headers
+==========================
+By default the following values will be used for the preflighted OPTIONS request:
+
+* **Access-Control-Allow-Methods**: 'PUT, POST, GET, DELETE, PATCH'
+* **Access-Control-Allow-Headers**: 'Authorization, Content-Type, Accept'
+* **Access-Control-Max-Age**: 1728000
+
+To add an additional method or header or allow less headers, simply pass additional values to the parent constructor:
+
+.. code-block:: php
+
+    <?php
+    namespace OCA\MyApp\Controller;
+
+    use \OCP\AppFramework\ApiController;
+    use \OCP\IRequest;
+
+    class AuthorApiController extends ApiController {
+
+        public function __construct($appName, IRequest $request) {
+            parent::__construct(
+                $appName, 
+                $request, 
+                'PUT, POST, GET, DELETE, PATCH',
+                'Authorization, Content-Type, Accept',
+                1728000);
+        }
+
+    }
\ No newline at end of file

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-owncloud/owncloud-doc.git