Motivation 

Why not EXT:nnrestapi? 

EXT:nnrestapi is an endpoint framework: you write a PHP class extending AbstractApi, annotate its methods, and return data however you choose. This gives maximum flexibility, but shifts all responsibility to the developer:

• No built-in relation loading. Returning Extbase domain objects hands serialization to TYPO3's standard DataMapper, which resolves every relation property individually during JSON conversion. A 20-item collection with 2 relation types produces the same 41 queries as any Extbase-based approach.
• No built-in filtering, pagination, or validation. Each endpoint is custom PHP. Adding a filter means writing a query constraint by hand; pagination requires manually counting rows and slicing results. Every resource needs its own implementation.
• No configuration model. There is no declarative description of a resource's shape, access rules, or allowed operations. Everything is imperative code inside action methods, growing linearly with the number of resources.
• Plain JSON output. Responses are plain JSON — no Hydra JSON-LD, no @context, no @type, no discoverable collection links.

nnrestapi is a reasonable choice for bespoke, one-off endpoints where the flexibility is genuinely needed. It is a poor fit for exposing multiple resources uniformly.

Why not EXT:t3api? 

EXT:t3api is the closest prior art — Hydra JSON-LD output, built-in filtering, pagination, serialization groups, and an API-Platform-inspired annotation model. It is a mature extension. The core limitation is the persistence layer:

• Built on Extbase DataMapper. Resources must be Extbase domain models (AbstractDomainObject subclasses). Queries use PersistenceManagerInterface::createQueryForType(), and all relation properties are resolved via Extbase's DataMapper.
• N+1 queries for embedded relations. DataMapper resolves relations through LazyLoadingProxy objects fetched on first access. Serializing 20 articles with 2 embedded relation types fires 41 database queries — one for the collection plus one per relation per row.
• Extbase model required per resource. Exposing a table from a third-party extension that ships no domain model class requires creating one.

Why not the TYPO3 Record API? 

The Record API introduced in TYPO3 v13 provides RecordFactory and typed Record objects with lazy relation resolution. It is a solid foundation for Fluid templates, but has key limitations for API use:

• Per-record hydration overhead. RecordFactory::createResolvedRecordFromDatabaseRow() instantiates a Record object per row, transforms each field through RecordFieldTransformer, and wraps relations in LazyRecordCollection or RecordPropertyClosure closures. For a collection of 20 records with 5 relation columns, this creates 20 Record objects + 100 lazy wrappers — before any relation is even accessed.
• No batch relation loading. When serializing a collection to JSON, every lazy relation fires a separate query on first access. 20 articles × (1 color + 1 category MM) = 41 queries. The GreedyDatabaseBackend mitigates this by pre-fetching an entire foreign table by PID, but this over-fetches and only helps within a single page context.
• Designed for rendering, not serialization. Calling $record->toArray() force-instantiates all lazy closures. There is no depth control, no cycle detection, and no way to configure which relations to embed vs. return as references.

Why not Extbase alone? 

Extbase's DataMapper suffers from the classic N+1 query problem. Each relation property on each domain object triggers a separate getPreparedQuery() call. The @Lazy annotation defers queries but doesn't batch them.

Why not EXT:headless? 

EXT:headless replaces TYPO3's HTML output with JSON via TypoScript JSON content objects. It uses the same rendering pipeline (CONTENT cObjects, DataProcessors) and executes the same queries as a normal page render. The benefit is smaller payloads for the frontend, not fewer database queries.