ithilgers / api-export
Token-secured JSON feed API for TYPO3 records (events from sf_event_mgt, news from georgringer/news), extendable via providers
Package info
github.com/ithilgers/api_export
Type:typo3-cms-extension
pkg:composer/ithilgers/api-export
Requires
- php: >=8.1
- typo3/cms-backend: ^12.4
- typo3/cms-core: ^12.4
- typo3/cms-frontend: ^12.4
Requires (Dev)
- derhansen/sf_event_mgt: ^7.0
- georgringer/news: ^12.0 || ^13.0
- phpunit/phpunit: ^10.5
- typo3/testing-framework: ^8.2
Suggests
- derhansen/sf_event_mgt: Required for the 'events' resource (^7.0 || ^8.0)
- georgringer/news: Required for the 'news' resource (^12.0 || ^13.0)
Provides
None
Conflicts
None
Replaces
None
README
Token-secured JSON feed API for TYPO3 records. External consumers fetch events, news and other records as machine-readable JSON, each with its own token and its own set of data.
Included resources (providers):
events– events fromderhansen/sf_event_mgtnews– news fromgeorgringer/news
Features
- Resource-oriented API:
GET /api/v1/{resource}with pagination, path prefix configurable - Token per consumer: Each API client has its own secret token, sent as HTTP header (
X-Feed-Tokenby default), with active flag and validity period - Grants per resource: Per client and resource you define which data is delivered – storage folders (optionally recursive), categories (include or exclude, optionally with subcategories), maximum number of items and resource-specific settings, just like an instance of the list plugin
- Detail links: Every item contains an absolute link to its detail page, built by the router of the target site, configurable per storage folder and inherited by subfolders; news of the type "internal page" or "external URL" link to their target
- Safe defaults: Data is always delivered as for an anonymous visitor – hidden, scheduled, access-restricted and deleted records, protected folders and workspace drafts never; logins in the request change nothing; responses are never cached by proxies
- Token protection: Tokens are generated by the system and shown only once; only their SHA-256 hash is stored. Copied clients get no usable token and stay deactivated. Clients can only be managed by admins
- Rate limit: Requests without a valid token are limited per IP address (
429), requests with a valid token are never blocked - Consistent errors: All responses are JSON with a meaningful status code – never an HTML error page or a redirect, independent of the root page of the site
- Extendable: Add further record types via a provider class, adjust items via a PSR-14 event
- Localized: English and German backend labels
Why This Extension?
Partner websites, apps or portals often need the same events or news that are shown on the website – but filtered differently per partner, and not publicly accessible. This extension delivers exactly that from the existing records, without duplicate data maintenance and without changes to the source extensions.
Installation
Via Composer (recommended)
composer require ithilgers/api-export
Activation
After installation, activate the extension in the Extension Manager or via CLI:
vendor/bin/typo3 extension:setup
Then:
- Update the database schema (Maintenance → Analyze Database) to create the tables for API clients, grants and detail page mappings.
- Flush all caches.
- Check:
GET /api/v1/eventswithout a token must return401as JSON. - Create an API client with a grant (see Usage) and copy its token from the form.
No static template or plugin needs to be included; the extension configuration comes with working defaults.
Before the First Consumer
-
Storage folders inside the site: If the folders holding the events or news are outside the page tree of the site, TYPO3 cannot resolve the speaking detail URLs and the links in the feed lead to a
404. -
Speaking detail URLs: Links are built by the regular site routing. Without a route enhancer for the respective plugin they contain query parameters including a
cHash(but still work). Example for news in the site configuration (limitToPages= uid of the news detail page):routeEnhancers: NewsDetail: type: Extbase limitToPages: [123] extension: News plugin: Pi1 routes: - routePath: '/{news_title}' _controller: 'News::detail' _arguments: news_title: news defaultController: 'News::detail' aspects: news_title: type: PersistedAliasMapper tableName: tx_news_domain_model_news routeFieldName: path_segment
-
Proxy or cache in front of TYPO3: The token header must be passed through to TYPO3, and
/api/v1/…must not be cached. All responses sendCache-Control: private, no-storefor this purpose. ConfigurereverseProxyIPso that the limit of failed attempts applies to the real IP address of the caller (see Configuration).
Configuration
Extension Configuration
Settings → Extension Configuration → api_export:
| Key | Description | Default |
|---|---|---|
basePath |
Path prefix of the API URLs (api/v1 → /api/v1/events) |
api/v1 |
headerName |
HTTP header that carries the token | X-Feed-Token |
defaultLimit |
Items per page without ?limit= |
100 |
maxLimit |
Highest allowed value for ?limit= |
500 |
failedAttemptsLimit |
Requests without a valid token per IP address and time window; further ones get 429. 0 = no limit |
10 |
failedAttemptsInterval |
Time window for failedAttemptsLimit, e.g. 15 minutes, 1 hour |
15 minutes |
Everything else is configured in the grants.
Failed attempts: only requests without a valid token are counted, per IP
address (rate limiter of the TYPO3 core, cache ratelimiter). Requests with a
valid token are never counted or blocked, also not from an IP address that
reached the limit. Rejected requests are logged as a warning with IP address
and path, never with the token: with an active limit only the first failed
attempt of an IP address per time window and once when the limit is reached,
without a limit every failed attempt.
Behind a proxy or load balancer, set
$GLOBALS['TYPO3_CONF_VARS']['SYS']['reverseProxyIP'](andreverseProxyHeaderMultiValue) so that TYPO3 sees the real IP address of the caller. Otherwise all consumers share the IP address of the proxy and count towards the same limit – valid tokens still work.
Usage
API clients and their grants are managed in the backend with the List module, e.g. in a dedicated folder.
API Client – who
One record per consumer (table tx_apiexport_domain_model_client). Clients,
grants and detail page mappings can only be managed by admins, even if
editors are granted access to the tables.
- Client name, Note
- Token – secret value the consumer sends in the header. It is generated by the system: 32 random bytes as 64 lowercase hexadecimal characters. It cannot be typed in, and the comparison is case-sensitive.
- Last used – maintained automatically
- Active, Access validity (valid from / until) – period in which the token is accepted; does not affect the delivered data
Getting a token – there are two ways, both store only the SHA-256 hash of the token and its last 4 characters; the token itself is never stored and cannot be displayed again:
-
In the backend form: a new client shows a freshly generated token with a copy button. Copy it before saving and pass it on to the consumer. Later, the form only shows "A token is stored, it ends with …". To replace it, check Generate new token, copy the new token and save – the previous token stops working at once. Closing the form without saving changes nothing.
-
On the command line:
vendor/bin/typo3 api-export:client:token <uid>
generates a new token for the client with this uid, saves it like the form (including the record history) and prints it once. Only the token is written to stdout, notes (e.g. "client is deactivated") to stderr. An unknown or deleted uid ends with exit code 1 and changes nothing.
This way consumers can be created, blocked, limited in time and revoked individually. A copy of a client (also as part of a copied page) is deactivated and gets an unknown token, together with copies of its grants; generate a new token for it before activating it.
Copies of the database: since only hashes are stored, no token can be
read from a database copy. A hash still works in the copy, though: in copies
for staging or development, deactivate the clients or generate new tokens
(api-export:client:token).
Grants – what
One grant per client and resource (inline records, table
tx_apiexport_domain_model_feed): once a client has a saved grant for a
resource, the backend no longer offers that resource for another grant of the
client.
A grant corresponds to an instance of the resource's list plugin – for a feed
that matches a public list, copy the plugin settings of that list:
| Grant field | Corresponds to in the list plugin |
|---|---|
| Resource | – (data type, /api/v1/<resource>) |
| Storage folders, Include subfolders | Record storage page / starting point, recursive |
| Categories, Category conjunction, Include subcategories | Category settings |
| Max. items | Max. records (queryLimit / limit), 0 = all |
| Settings (per resource) | Events: display, sorting · News: archive, sorting |
| Detail page | Detail page |
-
Without storage folders the grant delivers nothing.
-
Categories: the category conjunction includes or excludes records, like in the list plugins of news and sf_event_mgt:
Conjunction Delivered records orwith at least one of the categories (default) andwith all of the categories notorwith none of the categories notandwithout all of the categories at once Records without any category are kept by
notorandnotand. With "Include subcategories" a selected category also counts as present if the record carries one of its active subcategories – like in the news plugin. Forandwith subcategories, sf_event_mgt differs and requires all subcategories at once; the feed deliberately follows the news logic. -
Max. items limits the total; within that, consumers page through the result with
page/limit. -
Events – Display: as in sf_event_mgt:
current_future(upcoming and current, default),future,past,all. -
A grant can be deactivated individually (→
403). Should a client still have several grants for the same resource (e.g. two grants added without saving in between, or created by an import), the first one by sorting applies – if it is deactivated, the response is403, even if another one is active. Grants are never combined: to deliver records from several folders, add all folders to one grant.
Visibility is the same as in a public list for anonymous visitors: hidden,
scheduled, deleted and access-restricted (fe_group) records as well as
workspace drafts are never delivered; records for "all languages" (-1) are,
translations are not.
- Protected folders are never delivered. If a storage folder requires a
frontend group that excludes anonymous visitors – itself, or inherited from
a parent page with "Extend to subpages" – the grant delivers nothing from
this folder and its subfolders, even if the folder is entered directly.
"Hide at login" (
-1) is fine. A hidden folder is not protected: its visible records are delivered, as in the list plugin. Hidden and protected subfolders are skipped when subfolders are included. - Logins change nothing. The result is always that of an anonymous visitor, also if the request carries the session cookie of a frontend user or of a backend user with preview settings (hidden pages, simulated time, workspace).
Detail Links
Items contain a link field with an absolute URL to the detail page. The
detail page is resolved per record:
- Detail pages per folder – if the record is in a mapped folder, that folder's detail page applies.
- Inheritance to subfolders – otherwise the mapping of the nearest parent folder applies (via the rootline).
- Detail page of the grant. If that is empty as well,
linkis empty.
The link is built by the router of the site the detail page belongs to,
in that site's default language – also if it is a different site than the
one the feed was requested on. Route enhancers, aspects and the cHash of
that site apply. Since there is no typolink involved, link handlers,
absRefPrefix and mount points are not taken into account.
link is empty if there is no detail page, or if anonymous visitors
cannot reach it: hidden, deleted, outside its publishing dates or restricted
to a frontend group (also inherited via "Extend to subpages").
News types: as in the news list plugin, a news of the type internal page links to the selected page (empty if anonymous visitors cannot reach it, or if the target is not a page or URL), and a news of the type external URL links to the URL exactly as entered. Regular news link to the detail page.
API
GET /api/v1/{resource}[?page=<n>&limit=<n>] # e.g. /api/v1/events
curl -H "X-Feed-Token: <client-token>" \ "https://www.example.org/api/v1/events?page=2&limit=50"
The path is matched below the base of the site and of its language, so the
API answers on every site of the installation, with or without a language
prefix (/api/v1/events, /en/api/v1/events) and in subdirectory
installations (/portal/api/v1/events). A trailing slash is ignored. A
language prefix changes neither the data nor the links: the feed always
contains the default language and records for "all languages". The API is
only reachable at these URLs; there is no other entry point.
HEAD is answered like GET, without a body.
Responses (errors always as JSON {"error": …, "message": …}):
| Situation | Status |
|---|---|
| Valid token and active grant for the resource | 200 |
Invalid page/limit |
400 |
| Missing or invalid token | 401 |
| No (active) grant for this resource | 403 |
| Unknown resource or path below a resource (only with a valid token) | 404 |
Method other than GET/HEAD |
405 |
Too many requests without a valid token from this IP address (with Retry-After) |
429 |
| Error while generating the feed (logged) | 500 |
The token is checked before anything else: without a valid token the
response is always 401, so the API does not reveal to unauthorized callers
which resources exist.
Every response to a feed URL is JSON – never an HTML page or a redirect, whatever type or state the root page of the site has – and carries these headers, so that no proxy or CDN caches the token-dependent content:
Content-Type: application/json; charset=utf-8
Cache-Control: private, no-store
X-Content-Type-Options: nosniff
X-Robots-Tag: noindex, nofollow
Exception: middlewares that TYPO3 runs before this extension, the trusted
host check and the maintenance mode (pageUnavailable_force), answer as
for the whole site, i.e. possibly with HTML.
Pagination
page– page number, starting at 1 (default1)limit– items per page, 1 tomaxLimit(defaultdefaultLimit)
The response always contains total (all matching items), pages, page,
limit and count (items on this page). Consumers page until
page >= pages. A page beyond the last one returns items: [].
Example Output (/api/v1/events?limit=1)
{
"version": "1.0",
"resource": "events",
"total": 2,
"page": 1,
"pages": 2,
"limit": 1,
"count": 1,
"items": [
{
"uid": 123,
"title": "Photography Workshop",
"teaser": "Short description …",
"start": "2026-09-01T09:00:00+02:00",
"end": "2026-09-01T16:00:00+02:00",
"location": "Town Hall",
"city": "Sampletown",
"registrationRequired": true,
"link": "https://www.example.org/events/photography-workshop"
}
]
}
Extending
Adjusting the Output (PSR-14 Event)
Ithilgers\ApiExport\Event\ModifyFeedItemEvent is dispatched for every item
before output. A listener in your own site package can add, change or remove
fields – e.g. output the price of an event:
final class AddPriceToFeed { public function __invoke(ModifyFeedItemEvent $event): void { if ($event->getResource() === 'events') { $item = $event->getItem(); $item['price'] = (float)$event->getRecord()['price']; $event->setItem($item); } } }
# Configuration/Services.yaml of the site package Vendor\Sitepackage\EventListener\AddPriceToFeed: tags: - name: event.listener identifier: 'sitepackage/api-export-price'
getRecord() returns the complete record, getClient() the requesting client
(uid and title only, never token data) and getRequest() the feed request
(site, language, query parameters, normalizedParams, …).
The feed is generated by a middleware, before the page is resolved: there is
no $GLOBALS['TSFE'], no ContentObjectRenderer and no frontend template
setup, and frontend and backend users are never authenticated. Listeners
that depend on any of these do not work here; use the request and the TYPO3
APIs instead (e.g. the router of a site for links).
If a listener throws a PropagateResponseException (or
ImmediateResponseException), its response is delivered (e.g. to abort the
feed on purpose), only extended by the headers above; any other error
results in a JSON 500.
Adding a New Resource
-
Create a provider class. For a TCA table it is sufficient to extend
Ithilgers\ApiExport\Feed\Provider\AbstractTableFeedProvider(table, category field, sorting,buildItem()); visibility, language, folders, categories and pagination are handled by the base class. Alternatively implementFeedProviderInterfacedirectly. -
Make the resource selectable in the grant via a TCA override and give it a FlexForm for its own settings:
// Configuration/TCA/Overrides/tx_apiexport_domain_model_feed.php $GLOBALS['TCA']['tx_apiexport_domain_model_feed']['columns']['resource']['config']['items'][] = ['label' => 'Addresses', 'value' => 'addresses']; $GLOBALS['TCA']['tx_apiexport_domain_model_feed']['columns']['settings']['config']['ds']['addresses'] = 'FILE:EXT:sitepackage/Configuration/FlexForms/ApiExportAddresses.xml';
Providers are registered automatically as tagged services – no further wiring needed.
Technical Details
Requirements
- TYPO3 12.4 LTS
- PHP 8.1 or higher
- For the
eventsresource: sf_event_mgt 7 or 8 - For the
newsresource: news 12 or 13
How It Works
- The middleware (
FeedTokenAuthenticator) runs right after the site has been resolved (and after the maintenance mode), before the frontend and backend user authentication, redirects and the page resolver. It detects feed requests by the remaining path of the site routing (/{basePath}/{resource}below the base of the site and its language), allows onlyGET/HEADand checks token, resource, grant and pagination. All other requests are passed on unchanged. - For feed requests it answers itself, without TSFE, page rendering or plugin:
the
FeedRendererbuilds aFeedDemandfrom the grant (folders, category filter, settings, detail links, page) and calls the matching provider. Every item passes throughModifyFeedItemEvent. Errors are logged and answered with a JSON500– never with an HTML error page. - Providers query their table via Doctrine. If the source extension is not installed, the provider simply returns nothing.
Since the page tree is not involved, neither the type nor the access settings of the root page matter. The regular HTML output of the source extensions is not affected.
The field "Token" of a client is a virtual TCA field without database column
(type: none with its own renderType, so that the core never selects it,
e.g. as a column in the List module); a DataHandler hook turns it into
token_hash and token_hint. Code that writes client records directly into the database,
bypassing the DataHandler, has to set token_hash (SHA-256 of the token)
itself.
Running Tests
Unit and functional tests (real frontend requests through the complete
middleware stack) are located in Tests/. The extension comes with its own
Composer setup in .Build/ for this:
composer install # in the extension directory composer test # unit + functional tests (SQLite)
Against MariaDB/MySQL, e.g. in DDEV:
typo3DatabaseDriver=mysqli typo3DatabaseHost=db typo3DatabaseUsername=root \
typo3DatabasePassword=root typo3DatabaseName=apiexport \
.Build/bin/phpunit -c Build/phpunit/FunctionalTests.xml
Composer blocks TYPO3 12.4 because of security advisories (ELTS only). For the test installation this is disabled in
composer.jsonunderconfig.policy.advisories.block; it has no effect on projects that install the extension.
Tests and build files are excluded from release archives via .gitattributes.
Compatibility
| Extension Version | TYPO3 Version | PHP Version |
|---|---|---|
| 1.x | 12.4 LTS | 8.1+ |
Contributing
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Commit your changes
- Push to the branch
- Create a Pull Request
License
This extension is licensed under the GNU General Public License v2.0 or later.
Support
For bugs, feature requests, or questions:
- Open an issue on GitHub: https://github.com/ithilgers/api_export
Credits
Developed by Theodor Hilgers.
Keywords: TYPO3, API, JSON, feed, export, events, news, sf_event_mgt, token authentication