One of Drupal 8's API improvements was the introduction of the Typed Data API. This is because they provide auto-generated documentation of the API and auto-generated models for the consumer application. In summary, having schemas for our resources is a huge improvement for the developer experience. We can start to use the new model properties in Angular, iOS, Android, etc. Moreover, if the model in the consumer is auto-generated from the schema (one model per resource) then minor updates to the resource are automatically reflected in the model. That is important to many languages like Swift, Java, TypeScript, Flow, Elm, etc. More interestingly, since our schema comes with type information our schemas can be type safe.

Probably, there is a library for our consumer’s framework that does this already. That means that with a single implementation once, all of our consumers’ models are done forever. With that information, the consumer can generate its models automatically without developer intervention. All thanks to the schemas.Ī consumer could fetch the schemas for all the resources it needs at compile time or fetch them once and cache them for a long time. Whenever we make changes to a content type, that will be reflected in the HTTP API and the documentation automatically. When we enable JSON API and Open API you get a fully functional and accurately documented HTTP API for your data model. We are using the resource schemas in the Docson and Open API to generate automatic documentation. In general, a schema will help consumers to have a prior understanding of the data they will be fetching from the API, and what data objects they can write to the API.

This knowledge empowers consumers to add client-side form validation for the mail property. A schema also tells us that the mail property in the user resource is a string in the e-mail format. For instance, the schema tells the consumer that the body property is a JSON object that contains a value that is a string. In other words, a schema describes the shape of a resource and the datatype of each particular property.Ĭonsumers of data need schemas in order to set their expectations. Similarly, an API resource schema is a description of the data a particular resource can hold. Schemas are statically generated but normalizers are determined at runtime.Ī database schema is a description of the data a particular table can hold.They are expressed in the JSON Schema format. Schemas are generated from Typed Data definitions using the Schemata module.Schemas are key for the maintainability of the consumer’s data model.Schemas are key for an API's self-generated documentation.In past articles, we talked about request aggregation solutions for performance reasons, and how to leverage image styles in decoupled architectures. This article is part of the Decoupled hard problems series. That is because the serialization component in Drupal is so flexible that we can’t anticipate the final form our API responses will take, meaning the schema that our consumers depend on might be inaccurate. Unfortunately, this solution is often not good enough.

The Schemata module is our best approach so far in order to provide schemas for our API resources. Following DrupalCon Nashville, we are republishing (with updates) some of our key articles on decoupled or 'headless' Drupal as the community as a whole continues to explore this approach further. Comments from the original will appear unmodified. Note: This article was originally published on November 3, 2017.

Headless drupal maintainability