matt glaman

The Typed Data API, by example

Published on

There is a fantastic low-level API in Drupal called the Typed Data API. It is fantastic and provides a great way to handle data representation via a schema and validate that data's values. The Typed Data API is the foundation for the Entity API. Entities are composed of fields that are composed of properties, and each step is tied into the Typed Data API.

The Typed Data API was created to provide developers with a consistent way of interacting with data differently.

The Typed Data API integrates with the Validator component from Symfony. This allows us to apply constraints and validators to data type values and ensure they're valid. This is how content entity validation works. And, the beautiful part is that it can be used anywhere, especially when validating payloads to custom API endpoints. The Serialization module in Drupal core connects the Typed Data API into the Serializer component from Symfony. This allows us to seamlessly convert a timestamp into ISO8601 by having the correct data definition.

$definition = DataDefinition::create('timestamp');
$timestamp = $typed_data_manager->create($definition, 1640639271);

// Output: 1640639271
$timestamp->getValue();

// Gets a DateTime object, available for this data type class.
$timestamp->getDateTime();

// Output: 2021-12-27T21:07:51+00:00
$serializer->normalize($timestamp, 'json');

// Output: "2021-12-27T21:07:51+00:00"
$serializer->serialize($timestamp, 'json');

I first dove deep into the Typed Data API while working with the JSON:API module in Drupal core and doing ridiculous things with the Commerce API module. We had computed field types and needed to provide custom data definitions and data types for proper serialization.

Unfortunately, it is a part of Drupal core that received heavy development during the early Drupal 8 lifecycle but has fallen to the side. And that makes sense. It is very low-level. Not many developers interact with it since our data modeling system revolves around entities. With my work at Acquia, I have been working deeply with the Typed Data API again. This time, however, I wanted to try and educate other Drupal developers on how they may leverage the Typed Data API. The Typed Data API has some documentation. But it's a low-level and abstract idea, especially since its interactions are layered into the entity and field system.

So I decided to create a repository that showcases using the Typed Data API. Maybe it will never make sense for most developers to use, but perhaps it will help educate and enlighten Drupal developers about "what goes on" under the hood. So, I created the Typed Data API by Example repository.

It's a work in progress. I have started adding some basic examples and will be adding more. I hope you find it to be a valuable resource. I hope it inspires someone to find a way to expand the documentation on Drupal.org (I have no idea how since it's so technical.) Please, open a discussion or issue on the project if you have a request for an example or general question about using the Typed Data API.

For instance, we leverage custom data types in Simplytest.me to handle our payload for the launch request. Previously, it was many if and else statements checking various parts of the decoded JSON data. We decode the JSON, convert it to a data type, and then validate it against our data definition.

If you're curious, here are some relevant links on how we use data types in Simplytest.me, I still need to add this to the examples repository.

#

Want more? Sign up for my weekly newsletter