Contribute back! 

If you find any mistakes in the documentation or our code, we would be honoured if you could submit an issue or a pull request on Github in order to correct it.

Installation 

1. Install the extension from TER (sources are available on our GitHub repository).

In the context of a fully Composer setup, add in your root composer.json the following line before doing a `composer update`.

"require": {
    ...
    "aoe/restler": "2.*"
},

Because we are using a forked version of Restler (in order to be able to tag a stable version), you also need to add the following to your composer.json file.

"repositories": [
    {
        "type": "vcs",
        "url": "https://github.com/AOEpeople/Restler.git"
    }
],

2. Configure this TYPO3-Extension (in TYPO3 Extension-Manager; e.g. enable the online documentation of your REST-API). See the "Screenshots" section as well.
3. (Optional, but recommended) Install the TYPO3 Extension "TYPO3 Restler Examples".
4. Make the .htaccess changes described below:

The ".htaccess" file needs to be changed in order to make the REST API available.

# The api_explorer/.* MUST not hit TYPO3 (index.php) otherwise the requests will fail.
# This / (target) is only to prevent this to happen.
RewriteRule ^api_explorer/.*$ / [NC,QSA,L]

For Nginx use following rule

location ~^/api_explorer/ {
        rewrite ^/api_explorer/(.*)$ / last;
}

When this is done, than you can call the online documentation of your REST API via this URL:

www.example.com/api_explorer/

You also can call your REST API via this URL:

www.example.com/api/path-to-my-rest-api-endpoints/ .

Using TYPO3 Restler in our own extension (aka Exposing your own REST API) 

In order to offer a seamless integration of Restler ^[#f1] in TYPO3, this extension offers the interface "AoeRestlerSystemRestlerConfigurationInterface".

With classes implementing the "ConfigurationInterface", it is possible to configure Restler:

• Restler configuration can be defined (eg. supported response format)
• API endpoints can be defined
• Authentication classes can be defined (to protect API endpoints against unauthorized access)

Steps:

1. Create new PHP-class, which implements this Interface:

Aoe\Restler\System\Restler\ConfigurationInterface

You can use this PHP-class as example

Aoe\RestlerExamples\System\Restler\Configuration

Inside your PHP-class, you can configure the Restler framework:

• add API classes to the Restler object
• add Authentication classes to Restler object
• configure all static properties of PHP classes, which belong to the Restler framework

2. Register your PHP-class in your TYPO3-Extension (in ext_localconf.php-File)

Any class that implements the "AoeRestlerSystemRestlerConfigurationInterface" interface, must be declared in your extension "ext_localconf.php" file.

// Add the configuration class (in Extension 'restler'):
// In that configuration class, we can:
// - configure the cache directory
// - enable the extbase DI container
// - enable the online API documentation (if enabled in extension-configuration)
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['restler']['restlerConfigurationClasses'][] = 'Aoe\\Restler\\System\\RestlerConfiguration';

This way the following will be achieved:

• each extension can define any number of Restler configuration classes.
• the Restler configuration classes will only be called when an API endpoint is called (has no side-effects on normal calls of TYPO3).

3. Flush the TYPO3 System Cache

Using TYPO3 Restler from PHP libraries 

If you like to register API classes to the Restler object that are located outside of TYPO3 use the alternative GLOBAL array to set your configuration class which implements the "AoeRestlerSystemRestlerConfigurationInterface" interface:

// register API-Controller to TYPO3_Restler
$GLOBALS['TYPO3_Restler']['restlerConfigurationClasses'][] =
    yourNamespace\Configuration::class;

or you can directly register your REST-controller to an endpoint by using the GLOBAL array:

// register API-Controller to Restler
$GLOBALS['TYPO3_Restler']['addApiClass']['<YOUR_ENDPOINT_PATH>'][] =
    yourNamespace\yourRestController::class;

You just have to make sure that this setting is loaded by auto-loading. For example (via composer);

"autoload": {
    "files": [
        "fileWithGlobalConfigurationRegistration.php"
    ]
}

Caching of REST-endpoints - via TYPO3-Caching-Framework (experimental) 

Notice: Please note that this feature is experimental and could be removed in further releases.

When you want to use the TYPO3-Caching-Framework to cache the response of your REST-endpoints, you just need to add this two phpdoc-annotations in your REST-endpoint:

Example:

/**
 * The response of this REST-endpoint will be cached by TYPO3-caching-framework, because:
 *  - it's a GET-request/method
 *  - annotation 'restler_typo3cache_expires' (define seconds, after cache is expired; '0' means cache will never expire) is set
 *  - annotation 'restler_typo3cache_tags' (comma-separated list of cache-tags) is set
 *
 * The cache is stored in this TYPO3-tables:
 *  - cache_restler
 *  - cache_restler_tags
 *
 * @url GET my-rest-endpoint-which-should-be-cached
 *
 * @restler_typo3cache_expires 180
 * @restler_typo3cache_tags typo3cache_examples,typo3cache_example_car
 */
public function myRestEndpointWhichShouldBeCached() {

}

For details examples please refer to the restler_examples extension.

Exposing Internal APIs (experimental) 

Notice: Please note that this feature is experimental and could be removed in further releases. You can anytime make internal calls by using an HTTP client (for example Guzzle).

Just as you make HTTP calls to your public endpoints, it is possible to declare internal endpoints which you can use in a similar way, but using PHP.

You can practically decouple various components by exposing an internal API which is accessible via HTTP just during development.

Example:

$this->restApiClient->executeRequest('GET', '/api/rest-api-client/internal_endpoint/cars/1')

For details examples please refer to the restler_examples extension.

Examples 

To reduce the quantity of documentation required to use Restler, we provide also an example extension called Restler_examples available on TER. You can check first there how the endpoints work.

Also please refer to existing documentation regarding the Restler homepage ^[#f1].

ProductionContext [basic.productionContext] 

When productionContext is not set, than Restler will: - show debug information - not cache the routes (will parse the API-classes every time to map it to the URL)

Refresh cache [basic.refreshCache] 

You can use this configuration to rebuild cache every time in production mode. When in production mode, a cache file for the routes will be written in the cache directory by default.

Enable online documentation [basic.enableOnlineDocumentation] 

Defines whether to enable the online documentation of the REST-API.

Path to online documentation [basic.pathToOnlineDocumentation] 

Defines the path to the online documentation of the REST-API (e.g. www.example.com/<pathToOnlineDocumentation>/)