SDK

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.

PropertyTypeDescription
apiURLStringThe url of the Content API endpoint e.g. https://app.contento.io/api/v1
apiKeyStringYour API key for this project. Generate one in your account.
siteIdStringThe site ID for this project. You can find and copy this from the sites page.
isPreviewBooleanIf 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).

ParameterTypeDescription
idStringThe 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).

ParameterTypeDescription
slugStringThe slug property of the content object.
contentTypeStringThe 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.

PropertyTypeDescription
contentTypeStringRequired. The handle property of the content type you want to filter by.
limitIntegerThe amount of content objects per page. The API defaults this to 20 and has hard limit of 100.
sortByStringThe content object property to sort by. Defaults to published_at.
sortDirectionStringThe 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.

PropertyTypeDescription
paramsObjectThe 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.

PropertyTypeDescription
contentArrayAn array of content objects.
nextPage()?async Function or undefinedIf not undefined this will return a ContentAPIResponse object for the next page of content.
Previous
My Library