Search by

ithilgers / api-export

ithilgers

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

Statistics

Installs: 1

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

1.0.0 2026-11-18 14:12 UTC

This package is auto-updated.

Last update: 2026-11-19 10:36:35 UTC


README

TYPO3 12 License

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

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-Token by 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:

  1. Update the database schema (Maintenance → Analyze Database) to create the tables for API clients, grants and detail page mappings.
  2. Flush all caches.
  3. Check: GET /api/v1/events without a token must return 401 as JSON.
  4. 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 send Cache-Control: private, no-store for this purpose. Configure reverseProxyIP so 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'] (and reverseProxyHeaderMultiValue) 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:

  1. 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.

  2. 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
    or with at least one of the categories (default)
    and with all of the categories
    notor with none of the categories
    notand without all of the categories at once

    Records without any category are kept by notor and notand. With "Include subcategories" a selected category also counts as present if the record carries one of its active subcategories – like in the news plugin. For and with 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 is 403, 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:

  1. Detail pages per folder – if the record is in a mapped folder, that folder's detail page applies.
  2. Inheritance to subfolders – otherwise the mapping of the nearest parent folder applies (via the rootline).
  3. Detail page of the grant. If that is empty as well, link is 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 (default 1)
  • limit – items per page, 1 to maxLimit (default defaultLimit)

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

  1. 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 implement FeedProviderInterface directly.

  2. 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 events resource: sf_event_mgt 7 or 8
  • For the news resource: news 12 or 13

How It Works

  1. 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 only GET/HEAD and checks token, resource, grant and pagination. All other requests are passed on unchanged.
  2. For feed requests it answers itself, without TSFE, page rendering or plugin: the FeedRenderer builds a FeedDemand from the grant (folders, category filter, settings, detail links, page) and calls the matching provider. Every item passes through ModifyFeedItemEvent. Errors are logged and answered with a JSON 500 – never with an HTML error page.
  3. 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.json under config.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:

  1. Fork the repository
  2. Create a feature branch
  3. Commit your changes
  4. Push to the branch
  5. 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:

Credits

Developed by Theodor Hilgers.

Keywords: TYPO3, API, JSON, feed, export, events, news, sf_event_mgt, token authentication