Content Fetch JS SDK

While you can use the Content Fetch REST API using any programming language or framework, we've provided an official JavaScript SDK so you can integrate Agility CMS into your JavaScript project quick and seamlessly.

Supported Environments

The JavaScript SDK can be used within the browser (using NPM or a traditional direct script reference) and it can also be used in server-side node.js apps.

Using the SDK with NPM

Install the Agility Content Fetch JS SDK package into your project:

> yarn add @agility/content-fetch

Import the SDK when you need to use it in your JavaScript file(s):

import agility from '@agility/content-fetch'

Initialize the client with your GUID, API Key, and optionally set isPreview=true (if you are using a preview API Key). You can retrieve these values from API Keys in Agility.

Then you can use the client to execute requests in a variety of ways:

import agility from '@agility/content-fetch'

const api = agility.getApi({
  guid: '046a1a87',
  apiKey: 'defaultlive.2b7f3a91559d794bedb688358be5e13af2b1e3ae8cd39e8ed2433bbef5d8d6ac',
  isPreview: false
});

let contentListResult = await api.getContentList({ referenceName: 'posts', languageCode: 'en-us' });

//do something with the list of posts...
console.log(contentListResult);

Using the SDK with a Script Reference and Global Variable

While we highly recommend using an NPM set up for new projects, we understand that there are times where that just isn't feasible. For these cases, you can include the SDK by referencing it in a <script> tag and then accessing it using the assigned global variable called agility.

Add a reference to the agility-content-fetch.browser.js file:

<!-- Use a specific version (i.e. 1.1.0) --> 
<script type="text/javascript" src="https://unpkg.com/@agility/content-fetch@1.1.0/dist/agility-content-fetch.browser.js"></script>

<!-- Or, Use the latest version -->
<script type="text/javascript" src="https://unpkg.com/@agility/content-fetch@latest/dist/agility-content-fetch.browser.js"></script>

Next, you can access the global variable named agility, initialize the client, and start making API calls.

SDK Functions

The following are a collection of SDK functions and their response schemas. Some of the responses contain example data. We have provided links to the TypeScript interfaces for further reference. 

getApi

To instantiate a new Agility client, you must first use the getApi function, this will be used for all your subsequent function calls. 

var api = await agility.getApi({
  guid: '046a1a87',
  apiKey: 'defaultlive.2b7f3a91559d794bedb688358be5e13af2b1e3ae8cd39e8ed2433bbef5d8d6ac'
})

getContentList

Retrieves a list of content items by reference name.

var api = await agility.getApi({
  guid: '046a1a87',
  apiKey: 'defaultlive.2b7f3a91559d794bedb688358be5e13af2b1e3ae8cd39e8ed2433bbef5d8d6ac'
})

const list = await api.getContentList({
    referenceName: 'posts',
    languageCode: 'en-us'
})

Response Schema

{
  items: [
    { 
      contentID: number,
      properties: {
        state: number,
        modified: Date,
        versionID: number,
        referenceName: string,
        definitionName: string,
        itemOrder: number
      },
      fields: {
        // list of fields you have in your content model
        title: string,
        slug: string,
        date: Date,
        content: string
      }
    },
    ...
  ],
  totalCount: number
}

TypeScript Interface for Content List  

getContentItem

Gets the details of a content item by their Content ID.

var api = await agility.getApi({
  guid: '046a1a87',
  apiKey: 'defaultlive.2b7f3a91559d794bedb688358be5e13af2b1e3ae8cd39e8ed2433bbef5d8d6ac'
})

const item = await api.getContentItem({
    contentID: 21,
    languageCode: 'en-us'
})

Response Schema

{ 
  contentID: number,
  properties: {
    state: number,
    modified: Date,
    versionID: number,
    referenceName: string,
    definitionName: string,
    itemOrder: number
  },
  fields: {
    // list of fields you have in your content model
    title: string,
    slug: string,
    date: Date,
    content: string
  }
 }

TypeScript Interface for Content Item

getSitemapFlat

The sitemap, returned in a flat list, where the dictionary key is the page path. This method is ideal for page routing or generating sitemaps. 

var api = await agility.getApi({
  guid: '046a1a87',
  apiKey: 'defaultlive.2b7f3a91559d794bedb688358be5e13af2b1e3ae8cd39e8ed2433bbef5d8d6ac'
})

const sitemapFlat = await api.getSitemapFlat({
    channelName: 'website',
    languageCode: 'en-us'
})

Response Schema

{
  path: {
    title: string,
    name: string,
    pageID: number,
    menuText: string,
    visible: { menu: boolean, sitemap: boolean },
    path: string,
    redirect: string,
    isFolder: boolean
  },
  ...
}

TypeScript Interface for Sitemap Flat
TypeScript Interface for Sitemap Flat Item

getSitemapNested

Gets the sitemap as an array in a nested format, ideal for generating menus.

var api = await agility.getApi({
  guid: '046a1a87',
  apiKey: 'defaultlive.2b7f3a91559d794bedb688358be5e13af2b1e3ae8cd39e8ed2433bbef5d8d6ac'
})

const sitemapNested = await api.getSitemapNested({
  channelName: 'website',
  languageCode: 'en-us'
})

Response Schema

[
  {
    title: string,
    name: string,
    pageID: number,
    menuText: string,
    visible: { menu: boolean, sitemap: boolean },
    path: string,
    redirect: string,
    isFolder: boolean,
    children: [
      {
       title: string,
       name: string,
       pageID: number,
       menuText: string,
       visible: { menu: boolean, sitemap: boolean },
       path: string,
       redirect: string,
       isFolder: boolean,
       contentID: number,
       children: [ ... ]
     },
     ...
   ]
  },
 ...
]

TypeScript Interface for Sitemap Nested
TypeScript Interface for Sitemap Nested Item

getPage

Gets the details of a page by its Page ID.

const api = await agility.getApi({
   guid: 'ade6cf3c',
   apiKey: 'defaultlive.201ffdd0841cacad5bb647e76547e918b0c9ecdb8b5ddb3cf92e9a79b03623cb',
});
 
const page = await api.getPage({
   pageID: 1,
   locale: 'en-us'
})

Response Schema

{
  pageID: number,
  name: string,
  path: string,
  title: string,
  menuText: string,
  pageType: string,
  templateName: string,
  redirectUrl: string,
  securePage: boolean,
  excludeFromOutputCache: boolean,
  visible: { menu: boolean, sitemap: boolean },
  seo: {
    metaDescription: string,
    metaKeywords: string,
    metaHTML: string,
    menuVisible: boolean,
    sitemapVisible: boolean
  },
  scripts: { excludedFromGlobal: boolean, top: string, bottom: string },
  dynamic: {
    referenceName: string,
    fieldName: string,
    titleFormula:  string,
    menuTextFormula: string,
    pageNameFormula: string,
    visibleOnMenu: boolean,
    visibleOnSitemap: boolean
  },
  properties: { state: number, modified: Date, versionID: number },
  zones: { 
   MainContentZone: [ 
     {
      module: string;
      item: ContentItem;
      customData?: any;
     }
   ]
  }
}

TypeScript Interface for Pages
TypeScript Interface for ContentZone

getPageByPath

Gets the details of a page by its Path.

const api = await agility.getApi({
   guid: 'ade6cf3c',
   apiKey: 'defaultlive.201ffdd0841cacad5bb647e76547e918b0c9ecdb8b5ddb3cf92e9a79b03623cb',
});
 
const page = await api.getPageByPath({
   pagePath: '/blog/amazing-travel-guide',
   channelName: 'website',
   locale: 'en-us'
})

Response Schema

{
 sitemapNode: {
    pageID: number,
    name: string,
    path: string,
    title: string,
    menuText: string,
    visible: { menu: boolean, sitemap: boolean }
  },
  page: {
    pageID: number,
    name: string,
    path: string,
    title: string,
    menuText: string,
    pageType: string,
    templateName: string,
    redirectUrl: string,
    securePage: boolean,
    excludeFromOutputCache: boolean,
    visible: { menu: boolean, sitemap: boolean },
    seo: {
      metaDescription: string,
      metaKeywords: string,
      metaHTML: string,
      menuVisible: boolean,
      sitemapVisible: boolean
    },
    scripts: { excludedFromGlobal: boolean, top: string, bottom: string },
    dynamic: {
      referenceName: string,
      fieldName: string,
      titleFormula:  string,
      menuTextFormula: string,
      pageNameFormula: string,
      visibleOnMenu: boolean,
      visibleOnSitemap: boolean
    },
    properties: { state: number, modified: Date, versionID: number },
    zones: { 
     MainContentZone: [ 
       {
        module: string;
        item: ContentItem; // use getContentItem to fetch details
        customData?: any;
       },
       ...
     ]
    }
  }
}

TypeScript Interfaces for Pages

getGallery

Gets the details of a gallery by their Gallery ID.

const api = await agility.getApi({
  guid: 'ade6cf3c',
  apiKey: 'defaultlive.201ffdd0841cacad5bb647e76547e918b0c9ecdb8b5ddb3cf92e9a79b03623cb',
});

const gallery = await api.getGallery({
  galleryID: 22
})

Response Schema

{
  galleryID: number;
  name: string;
  description: string;
  count: number;
  media: [
     {
       mediaID: number;
       fileName: string;
       url: string;
       size: number;
       modifiedOn: Date;
       metaData: {
           title: string;
           description: string;
           linkUrl: string;
           pixelHeight: string;
           pixelWidth: string;
       };
     },
     ...
  ];
}

TypeScript Interface for Gallery
TypeScript Interface for Media Item
TypeScript Interface for Media Item Meta Data

getUrlRedirections

Retrieves a list of URL redirections

const api = await agility.getApi({
  guid: 'ade6cf3c',
  apiKey: 'defaultlive.201ffdd0841cacad5bb647e76547e918b0c9ecdb8b5ddb3cf92e9a79b03623cb',
});

const redirects = await api.getUrlRedirections({
  lastAccessDate: dateObj
})

Response Schema

{
   syncToken: number;
   items: [
      {
        id: number;
        originUrl: string;
        destinationUrl: string;
        statusCode: 301 | 302;
      },
      ...
   ];
}

TypeScript Interface for URL Redirection

getSyncContent

Retrieves a list of content items that need to be synced based on the provided sync content items token, and returns the next sync token.

const api = await agility.getApi({
  guid: 'ade6cf3c',
  apiKey: 'defaultlive.201ffdd0841cacad5bb647e76547e918b0c9ecdb8b5ddb3cf92e9a79b03623cb',
});

const content = await api.getSyncContent({
  syncToken: '0', //to start a new sync
  locale: 'en-us',
  pageSize: 500
})

// pass this back to the getSyncPages to resume
// the content until no sync token is returned.
const syncToken = pages.syncToken

Response Schema

{
   syncToken: number; // send back to continue sync
   items: ContentItem[]; // see getContentItem above
}

TypeScript Interface for Sync Content

getSyncPages

 Retrieves a list of pages that need to be synced based on the provided sync pages token, and returns the next sync token.

const api = await agility.getApi({
  guid: 'ade6cf3c',
  apiKey: 'defaultlive.201ffdd0841cacad5bb647e76547e918b0c9ecdb8b5ddb3cf92e9a79b03623cb',
});

const pages = await api.getSyncPages({
  syncToken: '0', //to start a new sync
  locale: 'en-us',
  pageSize: 500
})

// pass this back to the getSyncPages to resume
// the content until no sync token is returned.
const syncToken = pages.syncToken

Response Schema

{
   syncToken: number;
   items: Page[]; // see getPage above
}

TypeScript Interface for Sync Pages