JavaScript Client

The official JavaScript and Typescript client for the Contento Content API

For Next.js and Visual Preview support, see the Next.js toolkit docs.

Installation

npm install @gocontento/client

Basic usage

In most scenarios you will want to create a client once for the whole application, then re-use it whenever you make calls to the Contento API.

To assist in that, we have a createContentoClient() function that you can use:

import { createContentoClient } from "@gocontento/client";

// Create the client
const client =  createContentoClient({
    apiURL: "https://app.contento.io/api/v1",
    apiKey: "your_api_key",
    siteId: "your_site_id",
    isPreview: false,
});

Once you have the client instance, you can start fetching data. For example, you can use the ID of a page with the getContentById() method like so:

// Fetch a content object using the ID
const page = await client.getContentById("some_content_id");

Or, you can fetch a list of content using getContentByType()

// Fetch some content by type
const contentResponse = await client.getContentByType({
    contentType: "content_type_handle"
});

// Get the array of objects from the response
const contentData = contentResponse.content;

// Or, fetch the next page in the list
const nextPageResponse = await contentResponse.nextPage();

Creating a client instance

Use the createContentoClient() function to create a new ContentoClient instance. This method takes one parameter, which is a ContentoClientConfig object with the following properties.

Property	Type	Description
`apiURL`	`String`	The url of the Content API endpoint e.g. `https://app.contento.io/api/v1`
`apiKey`	`String`	Your API key for this project. Generate one in your account.
`siteId`	`String`	The site ID for this project. You can find and copy this from the sites page.
`isPreview`	`Boolean`	If `true`, the client will fetch the preview version of the content.

Example

// 1. Import the createContentoClient method 
import { createContentoClient } from "@gocontento/client";

// 2. Initialize the client instance with your settings
const client =  createContentoClient({
    apiURL: "https://app.contento.io/api/v1",
    apiKey: "your_api_key",
    siteId: "your_site_id",
    isPreview: false,
});

It’s a good idea to store those settings in your .env or something similar. Here’s how that might look:

.env

CONTENTO_API_URL=https://app.contento.io/api/v1
CONTENTO_API_KEY=your_api_key
CONTENTO_SITE_ID=your_site_id

lib/contento.js

import { createContentoClient } from "@gocontento/client";

export function createClient() {
    return createContentoClient({
        apiURL: process.env.CONTENTO_API_URL ?? "",
        apiKey: process.env.CONTENTO_API_KEY ?? "",
        siteId: process.env.CONTENTO_SITE_ID ?? "",
        isPreview: false,
    });
}

`ContentoClient`

The client returned from the createContentoClient() function is an Object with various methods available.

`getContentById()`

Fetch a content object by its ID: getContentById(id).

Parameter	Type	Description
id	`String`	The `id` property of the content object.

Returns a Promise that resolves to a content object.

Example

const page = await client.getContentById("some_content_id");

`getContentBySlug()`

Fetch a content object by its slug: getContentBySlug(slug, contentType).

Parameter	Type	Description
slug	`String`	The `slug` property of the content object.
contentType	`String`	The `handle` property of the content type you want to look within.

Returns a Promise that resolves to a content object.

Example

const content = await client.getContentBySlug("welcome-to-my-new-blog", "blog_post");

Unique slugs

Please note that slugs are only unique within any one given content type, so make sure to set up your routing to account for this.

`getContentByType()`

Fetch an array of content objects, filtered within a given content type: getContentByType(options).

This method takes an Object of options with the following properties.

Property	Type	Description
`contentType`	`String`	Required. The `handle` property of the content type you want to filter by.
`limit`	`Integer`	The amount of content objects per page. The API defaults this to `20` and has hard limit of `100`.
`sortBy`	`String`	The content object property to sort by. Defaults to `published_at`.
`sortDirection`	`String`	The direction to sort by, can be set to either `asc` or `desc` and defaults to `desc`.

Returns a Promise that resolves to a ContentAPIResponse object.

Examples

Get the first page of content objects, like you might want on a blog index page.

const response = await client.getContentByType({
     contentType: "blog_post"
});

const contentArray = response.content;

Get all pages of content in a given content type.

let response = await client.getContentByType({
    contentType: "blog_post",
    sortBy: "published_at",
    sortDirection: "desc"
})

let content = [...response.content];

// Build an array of content until there are no more pages
while(response.nextPage){
    response = await response.nextPage();
    content = content.concat(response.content);
}

`getContent()`

A thin wrapper for the Content API: getContent(options).

This method takes an Object of options with the following properties.

Property	Type	Description
`params`	`Object`	The request parameters to pass to the Content API. See all available options in the API docs.

Returns a Promise that resolves to a ContentAPIResponse object.

Examples

Get the 3 latest blog posts created by a specific user.

const response = await client.getContent({
    content_type: "blog_post",
    author: "some_author_id",
    limit: 3
});
const posts = response.content;

Get all blog posts in alphabetical order, we limit by 50 here to reduce the overall number of requests.

let response = await client.getContent({
    content_type: "blog_post",
    sort_by: "name",
    sort_direction: "asc",
    limit: 50
});
let content = [...response.content];

// Build an array of content until there are no more pages
while(response.nextPage){
    response = await response.nextPage();
    content = content.concat(response.content);
}

`ContentAPIResponse`

This response object is returned by many of the ContentoClient methods and has the following properties.

Property	Type	Description
`content`	`Array`	An array of content objects.
`nextPage()?`	`async` `Function` or `undefined`	If not `undefined` this will return a `ContentAPIResponse` object for the next page of content.