REST APIs

Offering a RESTful API is not different from creating a :doc:`route <../basics/routing>` and :doc:`controllers <../basics/controllers>` for the web interface. It is recommended though to inherit from ApiController and add #[CORS] attribute to the methods so that web applications will also be able to access the API.

<?php
namespace OCA\MyApp\Controller;

use OCP\AppFramework\ApiController;
use OCP\AppFramework\Http\Attribute\CORS;
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:

<?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:

<?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);
    }

}

Relation of REST and OCS

There is a close relationship between REST APIs and :ref:`OCS <ocscontroller>`. Both provide a way to transmit data between the backend of the app in the Nextcloud server and some frontend. This is explicitly not about :ref:`HTML template responses <controller_html_responses>`.

State-of-the-Art methods and comparison

The following combinations of attributes might be relevant for various scenarios:

Plain frontend route: Controller class
OCS route: OCSController class
OCS route with CORS enabled: OCSController class and #[CORS] attribute on the method

There are different ways a clients might interact with your APIs. These ways depend on your API configuration (what you allow) and on which route the request is finally made.

Access from web frontend means the user is accessing the Nextcloud web frontend with a web browser.
Access from non-browser is if the user accesses the resource or page using something that is not a web browser, like an Android app or a curl command.
Access from external website means that the user browses some third party web site and data from your Nextcloud server appears. The other website has to embed/load/use images, JSON data, or other resources from a URL pointing to the Nextcloud server, to be able to do this.

Comparison of different API types
Description	Controller class	OCSController class	OCSController class & CORS on method
URL prefix (relative to server)	/apps/<appid>/	/ocs/v2.php/apps/<appid>/	/ocs/v2.php/apps/<appid>/
Access from web frontend	yes	yes	yes
Access from non-browser	partial [1]	yes	yes
Access from external website	no	no	yes
Encapsulated data	no	yes (JSON or XML)	yes (JSON or XML)

Methods from Controller classes can return DataResponse objects similar to OCSController class methods. For methods of a Controller class, the data of this response is sent e.g. as JSON as you provide it. Basically, the output is very similar to what json_encode would do. In contrast, the OCSController will encapsulate the data in an outer shell that provides some more (meta) information. For example a status code (similar to the HTTP status code) is transmitted at top level. The actual data is transmitted in the data property.

As a rule of thumb one can conclude that OCS provides a good way to handle most use cases including sufficient security checks. The only exception to this is if you want to provide an API for external usage where you have to comply with an externally defined API scheme. Here, the encapsulation introduced in OCS and CSRF checks might be in your way.

Historical options

Before Nextcloud 30 the plain Controller classes' methods did not respect the OCS-APIRequest header. Thus, to provide access to this type of controller methods for external apps, it was necessary to use the #[NoCSRFRequired] attribute (or the corresponding @NoCSRFRequired annotation).

The following combinations of attributes were relevant for various scenarios:

Plain frontend route: Controller class
Plain frontend with CRSF checks disabled: Controller class and #[NoCSRFRequired] attribute on the method
Plain frontend route with CORS enabled: Controller class and #[CORS] and #[NoCSRFRequired] attributes on the route
OCS route: OCSController class
OCS route with CORS enabled: OCSController class and #[CORS] attribute on the method

Comparison of different API types
Description	Controller class	Controller class with NoCSRFRequired on method	Controller class with NoCSRFRequired and CORS on method
URL prefix (relative to server)	/apps/<appid>/	/apps/<appid>/	/apps/<appid>/
Access from web frontend	yes	yes (CSRF risk)	yes (CSRF risk)
Access from non-browser	no	yes	yes
Access from external website	no	no	yes
Encapsulated data	no	no	no