Content Handling with WaterwheelJS

In my previous blog post in this Waterwheel series, I detailed the basics of Waterwheel.js: how to set it up in server-side or client-side JavaScript, and how resource discovery can bring Drupal-backed applications and traditional Drupal implementations closer together in unprecedented ways. In this post, I explore how to manipulate content with Waterwheel.js.

Drupal 8's REST API comes with CRUD (create, read, update, and delete) operations available on content entities (e.g. nodes, users, and taxonomy terms) by default, which means that Drupal-backed applications have a range of possibilities when it comes to interacting with content in a Drupal repository. In Drupal 8.2, resources available via REST also include configuration entities, which are now retrievable via GET queries.

Setting up a Drupal content store

Before you get started, you may wish to set up some content on Drupal. This section header is a bit of a misnomer, because setting up a Drupal content store is synonymous with installing a Drupal site and populating it with content. For simplicity's sake, in this walkthrough, we'll be using the Article and Basic page content types, as well as a custom content type called Product.

Setting up Drupal on your local machine is easy with Acquia Dev Desktop. First, clone the most up-to-date version of Drupal from GitHub and install Composer dependencies:

Using Acquia Dev Desktop, click on the plus button and select Import new local site. Fill in the details; to ascertain the codebase location, select the drupal directory just created by the Git clone operation. Then, install Drupal normally by navigating to the domain you indicated. You can pay a visit to Acquia's help center for more details about using Acquia Dev Desktop.

Once you have an installed site, you can generate some initial filler content. With Drush, a command-line tool for Drupal, you can very quickly generate nodes (drush genc), taxonomy terms (drush gent), and users (drush genu). Visit the helpful resource Drush Commands for more information about Drush.

The series of commands below will create twenty nodes of various types, twenty taxonomy terms within the preexisting Tags vocabulary, and twenty users.

Last but not least, if you have not enabled CORS (cross-origin resource sharing) support, you can make use of either core's opt-in CORS support in 8.2 or Sally Young's CORS module.

Reading and updating content entities: GET and PATCH

To perform a GET query, or read operation, on a node, you can simply use the method .get() on the api object, as you can see below. All queries in Waterwheel return ES6 promises.

The method .get() accepts two arguments, namely the identifier of the requested entity (required, e.g. nid, tid, uid, etc.) and the format of the response (optional, defaults to JSON), which in an out-of-the-box REST API could be JSON or XML.

To request an entity in XML format, include the corresponding format argument:

To perform a PATCH query, or update operation, against a content entity, you can use the .patch() method, which includes an additional body argument containing a Drupal-compatible JSON object. This comes before the final format argument. The following query adjusts the title and body of the node of type Article having an nid of 1.

When the promise is fulfilled, this PATCH query will return the newly manipulated JSON object.

Adding and deleting content entities: POST and DELETE

To create a new entity, or perform a POST request, you can invoke the .post() method in much the same way as an update operation. For instance, the following adds a node of type Basic page with the title Hello Drupal.

Finally, to execute a DELETE query, you can simply provide the identifier argument and call it a day!

Conclusion

As you can see, retrieving and manipulating Drupal content from the standpoint of Drupal-backed JavaScript applications is quite straightforward. By using Waterwheel.js' built-in ES6 promises, you don't need to worry about unwieldy AJAX requests, implementing your own XMLHttpRequests from scratch, or the specifics of core REST's authentication mechanisms.

Moreover, Waterwheel.js allows JavaScript developers to worry about building their user interfaces and client-side code rather than grappling with the nuances of Drupal's core REST API, such as query string parameters for correct formats and particular routes to reach the correct resource. Even if Drupal's core REST API evolves in any of these characteristics, as an intermediate abstraction, Waterwheel.js' API is well-positioned to remain optimal for JavaScript applications in the future.