mirror of
https://github.com/nextcloud/documentation.git
synced 2026-01-03 10:20:02 +07:00
2647cd93c7
This moves lots of pages around. The high-level changes are * Better main sections, so it's more *general*, *into*, *basics* and *details* * Move more general topics to a *Basic* section, which are not app-specific * Remove app docs to the stuff that is likely used, anything else goes into "Digging deeper" * Move general guides into a prologue * Try to *compress*/combine some pages with similar content * Try to have better consistencs on level ob abstraction across pages * Split app development and maintenance pages into two sections * Integrate bugtracker info into prologue * Integrate Android pages into client APIs section Signed-off-by: Christoph Wurst <christoph@winzerhof-wurst.at>
81 lines
2.5 KiB
ReStructuredText
81 lines
2.5 KiB
ReStructuredText
=========
|
|
REST APIs
|
|
=========
|
|
|
|
.. sectionauthor:: Bernhard Posselt <dev@bernhard-posselt.com>
|
|
|
|
Offering a RESTful API is not different from creating a :doc:`route <routes>` and :doc:`controllers <controllers>` for the web interface. It is recommended though to inherit from ApiController and add **@CORS** annotations to the methods so that `web applications will also 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 separate URL for the preflighted **OPTIONS** request that can 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/{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 to 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);
|
|
}
|
|
|
|
}
|