TYPO3 REST API foundation. Built using an own middleware stack
Powered by co-stack.com
This TYPO3 Extension adds a generic API capability to TYPO3. The strength of this extension lies in its integration in TYPO3 itself and its ease of being used by other extensions. If you want to create a fast and safe API in TYPO3 you should use this extension.
There is no purpose in installing this extension without another extension that requires it.
Creating an API endpoint with EXT:api is simple and fast. EXT:api and your extension must be installed for the following steps.
- Create your API endpoint class. It can be anywhere but it is good practice to put it in
Classes/Api. Name your class after its use case. (e.g.
Vendor\Packaga\Api\VersionApi). Your API class must implement the interface
\CoStack\Api\Api\Api. Return an array with some values to begin with.
- Create your API registration file in
Configuration/Api.phpand register your API class. The file must return an associative array. The associative index is the
ROUTE, or API endpoint name and will be part of the URL. Here is an example with the StatusApi class.
return [ 'status' => [ 'class' => \CoStack\Api\Api\StatusApi::class, ], ];
- Login as administrator to your TYPO3 Backend. Go to the root page (ID 0) and select the list module. Create a new API token. Your registered API class should show up in the API scope list. Give your token a name and add your API endpoint to the list of APIs in scope. Safe the token to generate the token's secret.
- You can test your API by using curl. Replace
ROUTEwith your values:\
curl -H "Accept: application/json" -H "X-T3API-TOKEN: <SECRET>" https://<DOMAIN>/api/<EXTKEY>/<ROUTE>\ Example:
curl -H "Accept: application/json" -H "X-T3API-TOKEN: a220d5a473232e636f845e0f6919981a1baf13e97758d83b2bde7c5ec68954b7" https://local.myproject.de/api/api/statusYou should see the array JSON encoded.
Content Type determination
Responses are always formatted based on certain criteria. Currently, there are 3 criterias which can determine the response content type. They are evaluated in the following order:
- URL file extension: Calling an API url with
.xmlat the end will force the response to be in that format.
- Accept header: Accept headers can contain multiple mime types. They will be ordered by priority and the first mime type which is supported will be used (see Formatter).
- Route defaults: Routes can define a default mime type that will be used when there is no file extension or accept header. Multiple mime types are tried in order until the first supported is found (see Formatter).
Formatter are classes that can convert a PHP array into another mime type.
The most used Formatter included in EXT:api is
Register your own formatter in
$formatterRegistry = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\CoStack\Api\Core\Response\FormatterRegistry::class); $formatterRegistry->register(\Vendor\Package\Api\Response\Formatter\QuirkyFormatter::class);
The EXT:api middleware stack is fully configurable.
Register your own middleware in
$middlewareRegistry = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\CoStack\Api\Core\Middleware\MiddlewareRegistry::class); $middlewareRegistry->register(\Vendor\Package\Api\Middleware\Middlewares\ShadyStuffMiddleware::class);
You can define the position of your middleware by passing other middlewares as second and third argument.
Have a look into
\CoStack\Api\Core\Middleware\MiddlewareRegistry::register if you want to know more.
API route configuration
Each API endpoint has a set of configuration options. This example shows the full set of configuration options:
<?php declare(strict_types=1); return [ '_default' => [ 'v1' => [ 'mimes' => [ 'application/json', ], ], 'public' => [ 'public' => true, ], ], 'v1/extension/version' => [ 'class' => \CoStack\Api\Api\ExtensionVersionApi::class, ], 'v1/file/info' => [ 'class' => \CoStack\Api\Api\FileInfoApi::class, ], 'v1/status' => [ 'class' => \CoStack\Api\Api\StatusApi::class, 'public' => true, ], 'v1/discovery' => [ 'class' => \CoStack\Api\Api\DiscoveryApi::class, 'mimes' => [ 'application/xml', ], ], 'public/discovery' => [ 'class' => \CoStack\Api\Api\PublicDiscoveryApi::class, 'mimes' => [ 'application/xml', 'application/json', ], ], ];
class: The FQCN of your class that implements the API.
public: Routes which are public don't require the
X-T3API-TOKENheader. They are always available.
mimes: Define default mime types for the response formatting. See
_defaultkey is reserved to define defaults for all routes matching the sub-keys. In this example
v2. All routes beginning with
v1will inhert the
'public' => truewhich will make all routes starting with
To develop and debug your API calls you should set TYPO3's
displayErrors to wither
1 for local development.
In public or production environments
displayErrors should be
-1 and your
devIPmask should be set.
Enabling this setting will show exception instead of failing silently.
Your API responses may be empty if something went wrong. You can add following options to your curl call to get more information:
-I: Display the response headers (especially usefull if you do not see any response).
-H "X-T3API-SAPI: cli": Force the exception to be rendered for CLI.
Following HTTP Status codes are currently implemented:
- 403: You did not include an authentication header (
X-T3API-TOKEN) or the provided secret is incorrect.
- 406: You did not include an
acceptheader in your request or the accepted mime is not supported. Always try with
- 429: You hit the hard rate limit. Increase the requests per minute in the extension settings.
You can set this to
0to disable the rate limiter, but you must be aware of security implications (e.g. DoS).
- 500: An exception occurred in your API class. Check the logs.
When you do not get the results you expect from an API call you can debug requests with xDebug and PhpStorm.
Please use the internet search if you have any questions about xDebug or PhpStorm. We will not answer inquiries on these topics.
- Create a new .http scratch file. Replace
ROUTEwith your values):
https://<DOMAIN>/api/<EXTKEY>/<ROUTE> Accept: application/json X-T3API-TOKEN: <SECRET>
- Add a stop point in
- Click on the green arrow left of the URL and select PHP Debug.
- If your project is set up correctly it should hit your stop point.