Web Services in Drupal

If you're interested in decoupling Drupal, there's a good chance you've heard at least some of the buzz in the Drupalverse about "headless" or decoupled Drupal. Or perhaps you watched Dries' keynote from DrupalCon Barcelona or read Dries' blog post about the future of decoupled Drupal. Whatever the case may be, this tutorial and the ones that follow will walk you through building a simple decoupled blog. In Dries' terminology the demo site we'll be building is "fully decoupled." While it would be trivial to adopt similar techniques to build a progressively decoupled site, let's dig a bit deeper into what it means to build a decoupled Drupal site.

Andrew Berry, from Lullabot, has written a great article asking Should you Decouple? Like most architectural decisions there are trade-offs to consider with a decoupled approach. Let's take a look at some of the pros and cons of a decoupled approach. Is it the right choice for your project?

There's been a lot written about API design, it's probably not surprising there are several books written about the subject. It also seems like nearly every cloud-based service provides an API to allow access to your data. In this tutorial, we'll attempt to condense this information and answer the following questions:

• Are there different types of API paradigms?
• What kinds of considerations do we need to make when building an API for our decoupled site?
• And, what's this REST thing everyone is talking about?

Let's dig into those questions one at a time.

At this point, whether we've decided to use a third-party pre-rendering service or we've written our own isomorphic JavaScript application to serve as the front-end of our website, our hosting requirements have definitely gotten more complex. Let's take a look at the continuum of decoupled site architectures and start to come up with a list of things to keep in mind when considering their hosting requirements.

The term web services has been around for quite a while. Given that web services is such a broad topic, let's define what web services are and how we are going to refer to them throughout this series so we are all on the same page.

This tutorial is an introduction to web services that will help you:

• Learn what a web service is.
• Understand that this series focuses on HTTP web services, and mostly on REST principles.
• Get some examples of APIs in the wild and what type of consumers they have.

By the end of this tutorial, you'll be able to define what web services are, and how we'll use the term in the context of these tutorials.

Traditional Drupal development using the render pipeline allows you to ignore the pitfalls of mixing content and presentation logic in your data model. In a scenario with multiple distribution channels, this separation becomes of critical importance.

In this tutorial we will learn how to:

• Understand the importance of presentation and content separation (delivering clean content, not caring about how to show that content)
• Develop strategies to avoid these presentational problems with minimal damage to the content API

By the end of this tutorial you'll have a better understanding of why keeping presentation data out of your content model is important, and some tips for doing so.

Identifing the fields in your data model that contain presentation data is an important part of documenting and planning your API. Examining your existing data model will help put you in the correct mindset when creating or changing it. It is important to reflect on the implications of each field for each hypothetical consumer (even consumers your API is not serving). This process will improve your content model and your API.

In this tutorial we will:

• Go through the article content type's data model
• Locate any fields that contain presentation data

The article model is created out of the box by Drupal when using the standard installation profile.

By the end of this tutorial you'll know how to do these checks, and identify presentation data in your content model, on any content type in your project.

In the last several years REST has been the de facto standard for web services. However, there are several common problems when developing websites and digital experiences with the traditional REST implementations. Luckily, those issues have solutions, either complete or partial.

Modern web service specifications like JSON:API and GraphQL implement those solutions, although they differ slightly in their implementation.

In this tutorial we will learn about:

• The problems of traditional REST implementations
• Common solutions to those problems, and how JSON:API and GraphQL deal with them

By the end of this tutorial you'll be able to explain some of the common pitfalls of REST-based APIs, and how JSON:API and GraphQL address those issues.

When you are implementing an HTTP API for a decoupled project, one of the critical, but often overlooked, aspects is the API documentation. Documenting your API will allow front-end developers (and you six months from now) to learn how to use that particular API.

In Drupal, there are several modules that can read your site configuration and generate documentation for you automatically.

In this tutorial we're going to:

• Learn about the importance of good documentation.
• Decide whether or not to use an existing specification for our API such as JSON:API or GraphQL.
• Review options for automatically generating documentation.

By the end of this tutorial you'll be able to decide whether or not using an existing documentation specification is a good fit for your project, and choose an option based on those available for use with Drupal.

It is important to have good up-to-date documentation about your web services. Doing so will boost developer productivity in a decoupled project. Drupal offers several tools that help maintain your API documentation with minimal effort.

In this tutorial we'll:

• Learn about the JSON schema format for describing data structures
• Generate schemas for our fake articles REST resource
• Visualize those schemas in a human-readable format

By the end of this tutorial you should be able to generate documentation for your REST resources that is kept up-to-date automatically by Drupal.