preston.so

Reprinted from the Acquia Developer Center with permission from DC Denison (Senior Editor, Acquia).

As Drupal is increasingly widely used as a back end for application ecosystems, developers of wildly diverse backgrounds are now retrieving and manipulating data from Drupal in unprecedented ways. With Drupal 8 and core REST support articulating an API-first vision for the decoupled future, Drupal is eminently well-prepared to back a bevy of applications with divergent approaches. There's just one problem: non-Drupal developers don't know Drupal.

That's where Waterwheel comes in. Waterwheel is an emerging ecosystem of software development kits (SDKs) built by the Drupal community which ease and accelerate development of applications in other technologies. If you will momentarily forgive the flawed metaphor, Waterwheel helps non-PHP and non-Drupal developers "speak" Drupal.

This blog post summarizes the motivations behind SDKs for Drupal-backed applications and how the Waterwheel team has worked to map out a trajectory for Drupal to be utilized not only by PHP and Drupal developers but also by developers of diverse backgrounds who might otherwise have never discovered or considered it.

The API-first CMS

API-first architectures have become increasingly commonplace as the concept of a content management system (CMS) continues to evolve. In the Drupal community, the Web Services and Context Core Initiative (WSCCI) confronted this trend early by providing the means for Drupal 8 sites to expose data for the benefit of other sites. Today, one Drupal back end is capable of powering a wide range of applications, whether ancillary single-page or native applications or other back-end applications.

In the last several years, the widening prevalence of application ecosystems has been greeted by the advent of the API-first or headless CMS (also referred to as decoupled CMS or “content as a service”). These are content management systems which lack front ends — as a rule — because their sole purpose is to export content for retrieval and manipulation by other applications. Examples include services such as Built.io, CloudCMS, Contentful, and Prismic, which all offer paid subscriptions to build and consume an API in the cloud.

These platforms all have one thing in common: Like Drupal, they are platforms that back application ecosystems. But this is only one half of the picture.

SDKs for building applications

The concept of a software development kit (SDK) is not new in web development, and neither is the idea of connecting an SDK to web services in order to power and supply a decoupled application. Headless CMS platforms like those mentioned above share another common characteristic: the maintenance and release of SDKs that accelerate application development. These SDKs are predominantly free and open-source, despite their dependency on a paid subscription to a headless CMS platform.

With Waterwheel, Drupal challenges these headless CMS services by not only offering a robust series of SDKs to assist application developers but also serving as the best free and open-source API-first CMS on the market. To make Drupal’s web services first-class out of the box, the API-first initiative has been driving progress on both core and contributed modules to improve the developer experience of reading and writing Drupal data. Though SDKs are not intrinsically tied to Drupal core development itself, they serve as an integral piece of Drupal-backed application ecosystems.

Currently, consuming Drupal data requires at least a basic understanding of Drupal’s REST API. As such, the shared mission of Waterwheel.js (formerly known as Hydrant) and Waterwheel.swift (formerly known as the Drupal iOS SDK) is to help developers building Drupal-backed applications in JavaScript and Swift query and manipulate Drupal data without having to learn about nuances such as the differences between core REST’s authentication mechanisms or its approach to serializing Drupal data, such as how fields of varied cardinality are exposed as JSON.

Waterwheel.js: Drupal for JavaScript developers

Over the last several months, a small team of developers within OCTO and contributors from the Drupal community have been collaborating on the initial minor versions of Waterwheel.js (formerly known as Hydrant), a helper SDK that aids JavaScript developers who need to query and manipulate Drupal data. Development is being led by Matt Grill, Ted Bowman, and Preston So, and the library is available as a project on NPM.

Because Waterwheel.js contains an HTTP client well-suited for Drupal, it can be employed on the server side to make API calls within Node.js during server-side execution of a JavaScript framework. It can also be used on the client side to make asynchronous API calls after the browser loads the bundled library. In this way, Waterwheel.js can be leveraged universally — the code to provision data can be shared across client and server.

You can incorporate Waterwheel.js on your existing Drupal sites to provide AJAX-like interactions, or you can use it in a manner similar to common HTTP clients in the JavaScript community such as superagent or axios. Moreover, Waterwheel.js is well-positioned for progressively and fully decoupled Drupal sites (fully decoupled usage on a separate domain relies on CORS support available in Drupal 8.2 or adding CORS headers in .htaccess), as it is intended to provide a strong foundation which JavaScript frameworks can build on.

The Waterwheel module is required by Waterwheel.js if you wish to implement resource discovery in your application. Resource discovery allows developers desiring client-side validation against server-side entities and their fields to prepopulate an object containing metadata about what entities and fields are available for retrieval and manipulation. Formerly, Waterwheel.js also supported the Entity Query API module and its query operations (e.g. ranges, sorts, and conditions), but this will be superseded in the next minor version by full integration with the emerging JSON API module, where Entity Query API development has migrated.

In sum, Waterwheel.js is uniquely versatile in that it can be used on both server (Node.js) and client (in the browser) and in progressively decoupled or fully decoupled settings. We’re excited to broaden the feature set currently available in Waterwheel.js, especially for a 1.0.0 release in time for DrupalCon Dublin (see our BoF about Waterwheel).

Waterwheel.swift: Drupal for Swift developers

We are also welcoming the Waterwheel.swift SDK, formerly known as the Drupal iOS SDK and the work of Kyle Browning, into the ecosystem as part of a growing suite of SDKs for Drupal-backed applications. Waterwheel.swift provides full support for consuming Drupal 8's core REST API as well as session management and authentication capabilities for the benefit of Swift applications.

Waterwheel.swift supports iOS, macOS, tvOS, and watchOS out of the box with plug-and-play functionality for each of these platforms. Because it leverages Swift, Waterwheel.swift benefits from massive performance gains over the Drupal iOS SDK’s foregoing Objective-C implementation and takes advantage of Swift’s closures, which means anyone who writes Swift will feel very comfortable using it.

For iOS, for instance, it provides a login button which can be placed in any desired location (or subclassed) and will handle showing a custom LoginViewController. To accelerate development even further, Waterwheel.swift also has a waterwheelLoginViewController that provides username and password fields, thus allowing you to incorporate Drupal login and logout functionality into your Swift application with minimal development time.

In an upcoming update, Waterwheel.swift will add full caching of all requests and objects pulled from Drupal. It will be configurable down to the request or globally, but a default for all requests will be included. A demo application of these features is also included in the GitHub repository.

All in all, Waterwheel.swift makes complex communication with Drupal effortless for Apple-driven applications. Because it is built with Swift, you can take advantage of next-generation coding from Apple at your fingertips, and, like Waterwheel.js, you can use it to communicate with Drupal directly without having to understand Drupal’s REST API.

Conclusion

While headless CMS platforms such as Built.io and Contentful benefit from open-source components in the form of application SDKs, Waterwheel spotlights Drupal 8 as a capable and effective API-first CMS that is entirely free and open-source, from data storage to API provisioning to application SDKs and everything in between. With the advent of Waterwheel, paying toward an expensive platform subscription is no longer required — in fact, the sky’s the limit for your unbridled Drupal-backed application ecosystem.

The story of Waterwheel has only just begun. Our ambitious vision is to build upon the successes of Waterwheel.swift’s wide range of application components and Waterwheel.js’ seamless integration with the Drupal core REST API. The end goal is to furnish an ecosystem of SDKs with two significant advantages: For site builders and editors, you will be able to assemble prefabricated Drupal-backed applications without the aid of a developer. For developers, you will have a robust and battle-tested foundation on which to build application components and accelerate Drupal-backed application development.

For instance, after our initial work on Waterwheel.js, our hope is to facilitate the construction of application components in major JavaScript frameworks such as Angular, Ember, or React which can be easily composed to rapidly create a fully decoupled Drupal-backed single-page application. To learn more and to discuss the eventual vision of the Waterwheel ecosystem as a whole, please join us at DrupalCon Dublin!

In upcoming blog posts in this Waterwheel series, we will explore specifics of each of the available SDKs: some of the features available in Waterwheel.swift and how to build a simple Drupal-backed JavaScript application using Waterwheel.js. We’d like to hear from you too, whether you’re a Waterwheel user, an application developer, or a welcome contributor, as we continue paving the way forward for API-first Drupal.

Special thanks to Kyle Browning for contributions to this blog post. Thanks also to Matt Grill and Ted Bowman for feedback during its writing.