1 of 23

TYPO3 & the benefits of a �a resource-oriented architecture

Thomas Maroschik

CTO & shareholder at DFAU GmbH,�the creators of toujou,�the TYPO3 website builder.��@tmaroschik

Hey!

Welcome to my talk about TYPO3 and the benefits of a resource-oriented architecture.

Short disclaimer:

This talk is pretty dense in terms of information, but don’t worry to miss something.�I’ll publish the slides, with my transcript directly afterwards.

Excuse me for reading a lot, but it’s hard to these things right and very easy to get them wrong.

My name is Thomas Maroschik and some of you may know me from Twitter or some other TYPO3 events.

If you want to know more, just talk to me later. �I’m curious to learn more about you.

I’m glad you made it to the last slot of the day. �An already long day.

For sure you’re all a bit tired,�and sleepy.

I don’t mind if you doze away. �But please don’t snore.

�Drifting away already?

�Starting to dream?

### CLICK ###

2 of 23

Imagine sitting in a train. Replying to comments of a tweet, changing the poster image of a YouTube video, being alerted about a product running out of stock and granting your colleague permission to use iStockphoto images in his blog post.

All from within TYPO3.

3 of 23

4 of 23

“…the World Wide Web is designed to be constrained by the REST [resource-oriented] series of limitations…“ ¹

“…central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface…“ ²

¹ https://en.wikipedia.org/wiki/Resource-oriented_architecture�² https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5

By applying the same design to TYPO3,�users can consume and produce web resources through a unified interface.

What is the web?

5 of 23

When the whole world speaks a certain language�and I want to communicate efficiently,�I would be better off as a native speaker.

TYPO3 should SPEAK, LISTEN and THINK like the web, to become an interconnected content hub.

Why should we care?

6 of 23

“…concept of a web resource has evolved during the Web's history, from the early notion of static addressable documents or files, to a more generic and abstract definition, now encompassing every "thing" or entity…“ ¹

¹ https://en.wikipedia.org/wiki/Web_resource

By applying the same design to TYPO3,�users can consume and produce web resources through a unified interface.

Did something change? Isn’t the web document-oriented?

7 of 23

By using the same concepts

Text hier einfügen
Text hier einfügen

Resources

how to distinguish concepts
how to describe concepts

Verbs

how to interact with resources
how to manipulate resources

Links

how to connect resources
how to discover resources

How can TYPO3 start to think like the web?

8 of 23

By applying the same constraints ¹

How can TYPO3 start to speak and listen like the web?

Client-Server�➔ separation of concerns, components evolve independently
Stateless�➔ requests/responses contain all data necessary to understand a message
Cache�➔ clients need to know if responses are cacheable and how they invalidate
Layered System�➔ each component cannot see beyond the immediate layer they are interacting with
Uniform Interface�➔ standardized way of communication

¹ https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1

By applying the same constraints like the web

The following constraints aren’t concrete implementations, but rather abstract requirements.�

### CLICK ###�Client-Server, means that something is consuming and something is serving.�There is a clear separation of concerns with an established contract between both parties.��### CLICK ###�Stateless, means essentially, that nothing, that I said before, changes how my next message is understood.�Every message contains all data necessary to understand it.

### CLICK ###

Caches can improve efficiency dramatically, especially in distributed systems.�But they are hard to implement as an afterthought.�This is why this constraint should be respected from the start.

### CLICK ###

The Layered System constraint, tells us basically that we need to cascade client-server interactions, and prevent clients from skipping a layer.�For example: a client accesses the external API, the server accesses internal API as a client, a server accesses a database as a client, and so on.�No external client should be able to access the database directly.

### CLICK ###

A Uniform Interface, means that clients should be able to access different resources on different services with the same interface.�Think of how browsers enable a user to access different resources.�But we will get to that later.

Let’s return to things again.�What can be a resource in TYPO3?

### CLICK ###

9 of 23

A resource is every information�that can be named ¹

Page
Content Element
Image
Site Configuration
Backend Layout

Tweet
Youtube Comment
Hubspot Contact
Analytics Report
Mautic Campaign

Form
Remote operation
Webhook
Permissions
Metadata

What can be a resource in TYPO3?

¹ https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2_1_1

10 of 23

A resource has common properties

Type/Kind ¹

All resources of the same kind share the same characteristics.

Page
Tweet
Webhook

Name/Identifier ¹

Distinguishes resources of the same kind within a namespace.

number: 1337
uuid: e48b3d30-b779-…
name: form-final-v4

Namespace (optional)

A scope in which identifiers of resources of the same kind are unique.

Page
Site
Youtube Channel

What makes something a TYPO3 resource?

¹ https://jsonapi.org/format/#document-resource-object-identification

11 of 23

A resource provides interactions�through verbs

How could we interact with TYPO3 resources?

create
get/list
update
patch
delete

move
translate
publish
archive
…

All verbs are individual per resource. Authors are advised to support the basic CRUD verbs.

12 of 23

A resource can be a subresource

owned by a parent resource
can be nested
collection or item
has individual verbs
allows for fine grained authorization

What if a TYPO3 resource is not enough?

e.g. comments
translations
versions
status
operations

13 of 23

Applying the same patterns fractally

How could we apply the constraints throughout the systems?

Constraint	internally	externally
Client - Server	e.g. Controller/Service - Repository	e.g. Browser/Service - API Endpoint
Stateless	changes to resources are single transactions�e.g. $repo->update($object)	changes to resources are single transactions�e.g. PUT /api/page/1234
Cache	resources expose versions/changes or lifetimes if cacheable�e.g. by implementing different interfaces	resources expose versions/changes or lifetimes if cacheable�e.g. HTTP Cache/ETag Headers
Layered System	require client - server role model between every layer through�hexagonal architecture that forms a self repeating pattern of the components

14 of 23

The uniform interface is�a standardized way of communication ¹

What’s the uniform interface to resources?

¹ https://restapilinks.com/uniform-interface/

how to identify
how to manipulate
how to discover
how to learn about characteristics

15 of 23

A resource or collection is identified by URIs ¹

How could we identify resources in TYPO3?

¹ https://en.wikipedia.org/wiki/Uniform_Resource_Identifier#URLs_and_URNs

URI�Uniform Resource Identifier

URN�Uniform Resource�Name

URL�Uniform Resource�Locator

identifies a resource by name in a particular namespace

e.g. urn:t3:page:1234

identifies a resource by its location

�e.g. http://example.org/foo/

internally

externally

16 of 23

A resource may have many representations.

Instances Of Classes implementing the Resource Interface
Arrays/Anonymous Objects
URIs

How could we manipulate resources in TYPO3?

HTML
JSON/YAML
RDF/JSON-LD
XML

internally (PHP)

externally (HTTP/gRPC/…)

Manipulation happens by interacting with the representations�via the resource provided verbs. (e.g. HTTP Methods/Class Methods/Commands)

17 of 23

A resource registry acts as a catalog

Single Registry Class Instance
Lists Available Resources With Metadata/Schema Resources
Code And Data Defined Resources

How could we find out about available resources and their characteristics in TYPO3?

Single API Endpoint
Lists Available Resources With Metadata/Schema Resources
OpenAPI v3 and OPTIONS Request

internally (PHP)

externally (HTTP/gRPC/…)

As interfaces are externally described via OpenAPI v3, a subset of JSON Schema,�all resources are constrained to the limitations of JSON Schema.

We ask a resource registry about the resources known to TYPO3.

The mechanism of asking the registry, might be represented differently internally and externally but they have a thing in common:

there is only one single source of truth, that aggregates all the metadata about resources.

As metadata and schema of resources fulfill all criteria of a resource, they can be resources themself with all implications.

Internally, some representations, like Instances of PHP Classes are already self-describing.�But is not the case for other data structures, like arrays or anonymous objects or data defined resources.

The same applies to the external API.�XML, JSON-LD, JSON-API or Protocol Buffers are self-describing.�But HTML or plain JSON isn’t.

A quick side note:

On the external side, we should try to stay as language agnostic as possible by using a representation�that forms the least common denominator between clients.

Over the last two decades JSON has become supported in pretty much every programming language and tool.

Thus we shouldn’t implement structures in resources, that cannot be represented as JSON and described with JSON Schema.

Back to the topic,�instead of browsing through a catalog,�we could use a more direct way to navigate through resources.�

What we’re missing here,�is links.

### CLICK ###

18 of 23

A resource link is a reference to a resource or collection that the client can follow ¹

Instance Of Resource Reference
URL or URN via Resource Registry

What role could links between TYPO3 resources play?

URL

internally (PHP)

externally (HTTP/gRPC/…)

¹ https://en.wikipedia.org/wiki/Hyperlink

It is not guaranteed that a link can actually be successfully followed.�The target resource might be temporarily or permanently unavailable.

Links are references to a resource or collection that the client can follow.

These can be represented internally as�instances of a Resource Reference Class,�a URN that can be resolved via the Resource Registry�or generally as an URL.

I have to point out, that links are established unilateral without the knowledge of the target resource.

Thus it’s not guaranteed that a link can actually be followed.

The target can be temporarily or permanently unavailable, or in some cases not yet available.

This introduces a new constraint of eventual consistency between resources.

Later you can decide for yourself whether this is an impediment or opportunity.

I need to emphasize that, collections can be also referenced by links.�In terms of relational databases,�a link is more like a query than a foreign key constraint.

Puh, that was a lot.

Let’s take a break.

### CLICK ###

19 of 23

Intermission

20 of 23

Establishing the uniform interface �internally first

How do we start implement this in TYPO3?

find first principles that guide the implementation (e.g. why are we doing this/that?)
derive inspiration from other successful implementations (e.g. Spring Data, Kubernetes)
find overlaps with good programming practices (e.g. DDD, hexagonal architecture, CQRS)
develop contracts that enforce the principles (e.g. Class Interfaces, Patterns)
be super defensive about what we allow in the first iterations (e.g. final/private first)
challenge all assumptions with prototypical implementations

By establishing the uniform interface internally first

The idea here is: if we’re fine with ourselves then going out will be a breeze.

OK, let’s go:

### CLICK ###

find first principles that guide the implementation (e.g. why are we doing this or that?)

### CLICK ###

derive inspiration from other successful implementations (e.g. Spring Data, Kubernetes)

### CLICK ###

find overlaps with good programming practices (e.g. DDD, hexagonal architecture, CQRS)

### CLICK ###

develop contracts that enforce the principles (e.g. Class Interfaces, Patterns)

### CLICK ###

be super defensive about what we allow in the first iterations (e.g. put final or private keywords everywhere first, and loosen the contracts very carefully)

### CLICK ###

challenge all assumptions with prototypical implementations

These steps should result in a first released version of a minimal framework, that provides a uniform interface to resources.

So what’s next?

### CLICK ###

21 of 23

Create building blocks that aid�in building domain specific applications

What’s next?

resource storage adapters (e.g. Doctrine ORM, Solr, Mongodb, Twitter API)
resource permissions (e.g. RBAC, ABAC, UMA, internally/externally stored, Keycloak)
resource editors (e.g. Lists, Forms, Data Grids, Image Editors)
resource events (e.g. Replication, Domain Events, Webhooks)
resource models (e.g. Documents, Hierarchies, Streaming, Event Sourcing)
resource mappers (e.g. API Platform)

Create building blocks that aid in building domain specific applications

The idea here is to build an ecosystem of loosely coupled components, built by specialists, that generalists - like integrators - can wire together to build apps.

What could those building blocks be?

### CLICK ###

resource storage adapters, that deal with Doctrine ORM, Solr, Mongodb, APIs

### CLICK ###

resource permissions, that offer various models of Access Control, like Role-Based, Attribute-Based, User-managed-Access, internally/externally stored, for example in Keycloak

### CLICK ###

resource editors, that provide various editing options for resources, like Lists, Forms, Data Grids or Image Editors

### CLICK ###

resource events, that track changes over time for Auditing, Replication, Domain Events or Webhooks

### CLICK ###

resource models, that help realizing Document Object Models, Hierarchies, Streaming, Event Sourcing

### CLICK ###

resource mappers, like an integration with API Platform

This list is by far not complete, and these are only the blocks we could come up with.

I’m curious to hear your thoughts and ideas.

### CLICK ###

22 of 23

What do you think?

Thank you for your attention.

23 of 23

Discussion