README

Repository: https://gitlab.sgalinski.de/typo3/sg_apicore

Please report bugs here: https://gitlab.sgalinski.de/typo3/sg_apicore/-/issues

Short Summary

Provides an API framework for TYPO3: Multi-API, Multi-Tenants, Attribute-based endpoint configuration, Logging, Token JWT Bearer auth, User auth, Entity CRUD registration, Custom Endpoints.

For detailed information, please refer to the Documentation in docs/.

Directory Structure

The extension follows a standard TYPO3 extension structure with a focus on clean separation of concerns:

Classes/
- Attribute/: PHP attributes for routing, configuration, and security (e.g., #[ApiRoute], #[RequireScopes]).
- Configuration/: Configuration readers and objects.
- Context/: Value objects for request context (e.g., TenantContext).
- Controller/: API controllers handling the requests.
- Domain/:
  - Repository/: Repositories for database access (e.g., TokenRepository).
- Middleware/: PSR-15 middlewares (e.g., ApiRequestMiddleware for request interception).
- Security/: Authentication and authorization logic (e.g., BearerTokenProvider, AuthContext).
- Service/
  - Tenant/: Tenant resolution logic and resolvers.
  - ApiRegistry.php: Service to register APIs and versions.
  - Router.php: FastRoute-based dispatcher.
Configuration/: TYPO3 configuration files (Services, Middlewares, TCA).
docs/: Technical documentation and guides.
tests/: Unit and functional tests.

Installation

Install the extension via composer:
```
composer require sgalinski/sg-apicore
```
Activate the extension in the TYPO3 Extension Manager.

Quick Start (3 Steps)

1. Register your Controller

Add your controller to Configuration/Services.php and tag it with sg_apicore.router:

$services->set(MyController::class)
    ->tag('sg_apicore.router');

2. Define an Endpoint

Use the #[ApiRoute] attribute in your controller action:

#[ApiRoute(path: '/hello', methods: ['GET'])]
public function helloAction(ServerRequestInterface $request): ResponseInterface {
    return $this->responseService->createSuccessResponse(['message' => 'Hello!']);
}

3. Access the API

Open your browser at https://your-domain.local/api/docs/ui/ to see the generated Swagger UI and test your new endpoint!

Testing

You can test the API by calling the health endpoint:

# Basic health check
curl https://your-project.local/api/health

# API-specific health check (if registered)
curl https://your-project.local/api/public/v1/health

The API path prefix is configurable via the extension configuration (default: /api/).

API Registration

To register a new API, you use the ApiRegistry service. Detailed configuration options can be found in the APIs & Registration Documentation.

use SGalinski\SgApiCore\Service\ApiRegistry;
use TYPO3\CMS\Core\Utility\GeneralUtility;

$apiRegistry = GeneralUtility::makeInstance(ApiRegistry::class);
$apiRegistry->registerApi('public', ['1']);

Writing Endpoints

Endpoints are defined using PHP attributes on controller methods. See Writing Endpoints for a full guide.

#[ApiRoute(path: '/my-endpoint', methods: ['GET'], apiId: 'public', version: '1')]
public function myAction(ServerRequestInterface $request): ResponseInterface {
    return $this->responseService->createSuccessResponse(['message' => 'Hello World']);
}

Standardized Responses

The ResponseService provides a unified way to create JSON responses, following RFC 7807 for errors. See Writing Endpoints - Responses.

Pagination

The extension provides a PaginationService to handle consistent pagination across endpoints. See Writing Endpoints - Pagination (Note: Add pagination details to docs if missing).

TCA Mapper

The TcaMapper service allows you to map TYPO3 database records to API response arrays based on the TCA. See TCA Mapper Documentation.

Auto-CRUD Resources

You can expose TYPO3 tables as API resources with full CRUD support. See Auto-CRUD Resources Documentation.

OpenAPI Documentation

The extension automatically generates OpenAPI 3.0 specifications. You can access Swagger UI at /api/{apiId}/v{version}/docs/ui. See OpenAPI Documentation.

Backend Module

The extension provides a TYPO3 Backend Module under System > API Core.

APIs & Versions: Overview and Swagger UI links.
Token Management: Create and manage Opaque and Refresh tokens.
Endpoints: List of all registered endpoints and their requirements.

See Authentication & Scopes - Backend for details.

Logging

Comprehensive logging for API requests and responses, including request tracking via a unique Request ID. See Logging Documentation.

Multi-Tenancy

Every API request runs in a TenantContext, usually derived from the TYPO3 Site. See Tenants Documentation.

Security & Authentication

Supports multiple auth modes (public, token, user) and scope-based authorization. See Authentication & Scopes.

Known Issues & Troubleshooting

Missing Authorization Header (Apache)

In some hosting environments (especially Apache with PHP via CGI/FastCGI), the Authorization header is stripped before it reaches PHP. If you experience "Authentication required" errors despite sending a valid token, add the following to your .htaccess file:

SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

The extension includes a fallback to check for HTTP_AUTHORIZATION and REDIRECT_HTTP_AUTHORIZATION, but this server-side configuration is the most reliable fix.

Legacy Support (Migration from sg_rest)

The extension provides a bridge to support legacy sg_rest clients. This includes:

Middleware for mapping old URL patterns.
Support for fe_users authentication tokens.
Emulation of the old response format.

Note: Legacy support is disabled by default. See the Migration Guide for details on how to enable and use it.

Architectural Decisions

For information on why we chose certain technologies and patterns, see our Architectural Decision Records at docs/adr/.

sgalinski / sg-apicore

Maintainers

Details