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

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

@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

  • 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

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

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.

Give it a go and grow your own herbs

There's nothing like having your own supply of fresh herbs, readily available and close at hand to use while cooking. Whether you have a large garden or a small kitchen window sill, there's always enough room for something home grown.

Outdoors

Mint

Mint is a great plant to grow as it's hardy and can grow in almost any soil. Mint can grow wild, so keep it contained in a pot or it might spread and take over your whole garden.

Sage

Like mint, sage is another prolific growing plant and will take over your garden if you let it. Highly aromatic, the sage plant can be planted in a pot or flower bed in well drained soil. The best way to store the herb is to sun dry the leaves and store in a cool, dark cupboard in a sealed container.

Rosemary

Rosemary plants grow into lovely shrubs. Easily grown from cuttings, rosemary plants do not like freezing temperatures so keep pots or planted bushes near the home to shelter them from the cold. It grows well in pots as it likes dry soil, but can survive well in the ground too. If pruning rosemary to encourage it into a better shape, save the branches and hang them upside down to preserve the flavor and use in food.

Indoors

Basil

Perfect in sunny spot on a kitchen window sill. Basil is an annual plant, so will die off in the autumn, so it's a good idea to harvest it in the summer if you have an abundance and dry it. Picked basil stays fresh longer if it is placed in water (like fresh flowers). A great way to store basil is to make it into pesto!

Chives

A versatile herb, chives can grow well indoors. Ensure the plant is watered well, and gets plenty of light. Remember to regularly trim the chives. This prevents the flowers from developing and encourages new growth.

Coriander (Cilantro)

Coriander can grow indoors, but unlike the other herbs, it doesn't like full sun. If you have a south facing kitchen window, this isn't the place for it. Although not as thirsty as basil, coriander doesn't like dry soil so don't forget to water it! Cut coriander is best stored in the fridge.

 
---
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

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.

Give it a go and grow your own herbs

There's nothing like having your own supply of fresh herbs, readily available and close at hand to use while cooking. Whether you have a large garden or a small kitchen window sill, there's always enough room for something home grown.

Outdoors

Mint

Mint is a great plant to grow as it's hardy and can grow in almost any soil. Mint can grow wild, so keep it contained in a pot or it might spread and take over your whole garden.

Sage

Like mint, sage is another prolific growing plant and will take over your garden if you let it. Highly aromatic, the sage plant can be planted in a pot or flower bed in well drained soil. The best way to store the herb is to sun dry the leaves and store in a cool, dark cupboard in a sealed container.

Rosemary

Rosemary plants grow into lovely shrubs. Easily grown from cuttings, rosemary plants do not like freezing temperatures so keep pots or planted bushes near the home to shelter them from the cold. It grows well in pots as it likes dry soil, but can survive well in the ground too. If pruning rosemary to encourage it into a better shape, save the branches and hang them upside down to preserve the flavor and use in food.

Indoors

Basil

Perfect in sunny spot on a kitchen window sill. Basil is an annual plant, so will die off in the autumn, so it's a good idea to harvest it in the summer if you have an abundance and dry it. Picked basil stays fresh longer if it is placed in water (like fresh flowers). A great way to store basil is to make it into pesto!

Chives

A versatile herb, chives can grow well indoors. Ensure the plant is watered well, and gets plenty of light. Remember to regularly trim the chives. This prevents the flowers from developing and encourages new growth.

Coriander (Cilantro)

Coriander can grow indoors, but unlike the other herbs, it doesn't like full sun. If you have a south facing kitchen window, this isn't the place for it. Although not as thirsty as basil, coriander doesn't like dry soil so don't forget to water it! Cut coriander is best stored in the fridge.

 
---
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