REST APIs

Offering a RESTful API is not different from creating a route and 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 OCS. 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 HTML template responses.

State-of-the-Art methods and comparison

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

1. Plain frontend route: Controller class

2. OCS route: OCSController class

3. OCS route with CORS enabled: OCSController class and #[CORS] attribute on the method

Warning

Adding the #[NoCRSFRequired] attribute imposes a security risk. You should not add this to your controller methods unless you understand the implications and be sure that you absolutely need the attribute. Typically, you can use the OCS-APIRequest header for data requests instead, in order to satisfy the CSRF checks in your API requests.

Warning

Adding the attribute #[CORS] alone is not sufficient to allow access using CORS with plain frontend routes. Without further measures, the CSRF checker would fail. So, enabling CORS for plain controllers is generally and highly discouraged.

You would have to disable the CSRF checks (one more security risk) or use the OCP-APIRequest header or send a CSRF token to successfully pass the checks. The latter requires dedicated JS code on the importing page.

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.

Hint

The discussion here is for data requests only. If you think of controller methods serving (HTML) templates, disabling CSRF is considered fine.

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)

[1]

The external app has to satisfy the CSRF checks. That is, you need to have the OCS-APIRequest HTTP request header set to true. This is only possible for Nextcloud 30 onwards, older versions do not respect the header.

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

Deprecated since version 30: The information in this section are mainly for reference purposes. Do not use the approaches in new code.

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:

1. Plain frontend route: Controller class

2. Plain frontend with CRSF checks disabled: Controller class and #[NoCSRFRequired] attribute on the method

3. Plain frontend route with CORS enabled: Controller class and #[CORS] and #[NoCSRFRequired] attributes on the route

4. OCS route: OCSController class

5. OCS route with CORS enabled: OCSController class and #[CORS] attribute on the method

Hint

The two scenarios involving the OCSController have not changed and, thus, the state-of-the-art documentation as noted above still holds true. Thus, these options are not reconsidered here again for simplicity reasons and to get the overall view more crisp.

The warnings about not using NoCSRFRequired and CORS as mentioned in the state-of-the-art section holds true here as well.

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