Skip to content
Drupal API Client

Quick Start

To get started we’ll show you how to:

  • Install the @drupal-api-client/json-api-client package.
  • Create an instance of the client.
  • Source a collection of nodes from your Drupal site.
  • Render data for a single node in a component.

Install using a package manager

Section titled “Install using a package manager”

You can install @drupal-api-client/json-api-client using the package manager of your choice.

Terminal window
npm install @drupal-api-client/json-api-client

Install using a CDN import

Section titled “Install using a CDN import”

@drupal-api-client/json-api-client can also be imported from a CDN like jsDelivr that supports bundling ES Modules.

<script type="module">
  import { JsonApiClient } from "https://esm.run/@drupal-api-client/json-api-client";
</script>

The example above imports the latest version of the package. In production you’ll likely want to specify a version.

<script type="module">
  import { JsonApiClient } from "hhttps://esm.run/@drupal-api-client/json-api-client@0.7.1";
</script>

Drupal Requirements

Section titled “Drupal Requirements”
  • The JSON:API module provided by Drupal core must be enabled on your Drupal site.
  • Optionally, you can install the Decoupled Router module to make use the getResourceByPath method.

Retrieve a collection of articles

Section titled “Retrieve a collection of articles”

First, create an instance of the client.

import { JsonApiClient } from "@drupal-api-client/json-api-client";


const client = new JsonApiClient("https://drupal-api-demo.party");

This creates a client using the specified baseUrl, but otherwise all default settings. It is also possible to pass in an options object to customize the client.

Next, use the client to get a collection of articles from Drupal.

import { JsonApiClient } from "@drupal-api-client/json-api-client";


const client = new JsonApiClient("https://drupal-api-demo.party");


const articles = await client.getCollection("node--article");

Below, you can explore the shape of the articles object sourced from a Drupal site with the Umami demo data installed.

Retrieve a single resource

Section titled “Retrieve a single resource”

Looking at the result of our articles collection, we can see that the first article has an id of d71e5f12-7be5-48d4-a3eb-c37473fc1f8f. For the sake of example, let’s retrieve this single article and display some results in a component.

To start, the code is very similar, but we’ll be using the getResource method and providing a second parameter of the id of the resource we want to retrieve.

(Use the tabs below to swap between the JavaScript code and the resulting article object.)

---
import { JsonApiClient } from "@drupal-api-client/json-api-client";


const client = new JsonApiClient(
  "https://drupal-api-demo.party",
);


const article = await client.getResource(
  "node--article",
  "d71e5f12-7be5-48d4-a3eb-c37473fc1f8f",
);
---

Now we can render data from our article object within a component.

---
import { JsonApiClient } from "@drupal-api-client/json-api-client";


const client = new JsonApiClient(
  "https://drupal-api-demo.party",
);
const article = await client.getResource(
  "node--article",
  "d71e5f12-7be5-48d4-a3eb-c37473fc1f8f",
);
---
<h2>{article.data.attributes.title}</h2>
<div set:html={article.data.attributes.body.processed} />

Retrieve a single resource by path

Section titled “Retrieve a single resource by path”

As we saw above, using getResource requires us to know the id of the resource we intend to retrieve. There will likely be cases where your front end application knows the requested path, but doesn’t know the id of the resource in Drupal that it should resolve to. In these cases the getResourceByPath method allows you to retrieve a single resource by providing the path instead of the id.

Let’s adapt our example of rendering an example article to use getResourceByPath.

---
import { JsonApiClient } from "@drupal-api-client/json-api-client";


const client = new JsonApiClient(
  "https://drupal-api-demo.party",
);
const article = await client.getResourceByPath(
  "/articles/give-it-a-go-and-grow-your-own-herbs",
);
---
<h2>{article.data.attributes.title}</h2>
<div set:html={article.data.attributes.body.processed} />

With a few lines of code, you’ve sourced data from your Drupal site and displayed it within your front end component. This is just the beginning of what is possible with the JSON:API Client. Continue on to experiment in an interactive playground, or jump to the next section for an in-depth tutorial.

Additional Resources

Section titled “Additional Resources”