README

This extension adds an easy way to provide custom API endpoints for your extensions.

Requirements

PHP ^8.2.
TYPO3 13.4

Documentation

This extension is a fork of the extension app_routes. It provides a simple way to create custom API endpoints in TYPO3.

Under the hood, it uses Symfonys Routing Component. to resolve the routes.

How to set up a new API endpoint

There are two ways to register API endpoints:

PHP Attribute Method - For global endpoints available across all sites (or optionally restricted to a specific site)
YAML Configuration Method - For site-specific endpoints (automatically restricted to the site that defines them)

Method 1: PHP Attribute (Global Endpoints)

To create a global API endpoint, create a class that implements the \Psr\Http\Server\RequestHandlerInterface and use the \PSVNEO\PsvneoEasyApi\Attribute\AsEndpoint attribute to define the endpoint's properties.

Property	Description	Default Value	Example Value
`name`	A unique name for the endpoint, used to identify it in the system.	Required	`dummy`
`path`	The path for the endpoint.	Required	`/api/my-endpoint`
`methods`	The HTTP methods the endpoint should respond to.	All methods	`['GET']`
`defaults.cache`	Indicates if the endpoint should be cached. Only available for `GET` and `HEAD` requests.	`false`	`true`
`defaults.tsfe`	Specifies if the endpoint requires a loaded TypoScript Frontend (TSFE).	`false`	`true`

namespace Vendor\MyExtensionName\Api;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;
use PSVNEO\PsvneoEasyApi\Attribute\AsEndpoint;
use TYPO3\CMS\Core\Http\JsonResponse;

#[AsEndpoint(
    name: 'my-endpoint',
    path: '/api/my-endpoint',
    methods: ['GET'],
    defaults: [
        'cache' => true,
        'tsfe' => true,
    ]
)]
final class MyEndpoint implements RequestHandlerInterface
{
    public function handle(ServerRequestInterface $request): ResponseInterface
    {
         // Your custom logic here...
        return new JsonResponse([
            'success' => true
        ]);
    }
}

Method 2: YAML Configuration (Site-Specific Endpoints)

For site-specific endpoints, you can define them in a YAML configuration file and import it in your TYPO3 site configuration. This ensures the endpoint is only available for sites that include this definition.

Step 1: Create a YAML file in your extension (e.g., Configuration/EasyApi.yaml):

easyApiEndpoints:
    my_api:
        handler: Vendor\MyExtensionName\Api\MyEndpoint
        name: my_api
        path: /api/my-endpoint
        methods:
            - GET
            - POST
        defaults:
            cache: true
            tsfe: true

Step 2: Create the request handler class (without the AsEndpoint attribute):

namespace Vendor\MyExtensionName\Api;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;
use TYPO3\CMS\Core\Http\JsonResponse;

final class MyEndpoint implements RequestHandlerInterface
{
    public function handle(ServerRequestInterface $request): ResponseInterface
    {
        // Your custom logic here...
        return new JsonResponse([
            'success' => true
        ]);
    }
}

Step 3: Import the YAML file in your site configuration (config/sites/<your-site>/config.yaml):

imports:
    -   resource: 'EXT:my_extension/Configuration/EasyApi.yaml'

Site-specific behavior: The endpoint will now only be available for the site that includes this configuration. If you try to access it from a different site, it will return a 404 error.

Important: Site config-based endpoints are registered during DI container compilation for optimal performance. After modifying endpoint configurations in site config YAML files, you must clear the TYPO3 cache to rebuild the container:

vendor/bin/typo3 cache:flush

This ensures your endpoint changes are picked up by the system.

psvneo / typo3-extension-easy-api

Maintainers

Details