zestyio-api-wrapper

0.1.12 • Public • Published 3 days ago

Zesty.io Node API Wrapper

Quickly access Zesty.io's Instance, Accounts and Media Management APIs.

Installation

This tutorial assumes you have npm and Node.js (8.9.4 or greater) installed, and have a package.json file for your project.

Install via npm:

npm install zestyio-api-wrapper

Include this line at the top of your JavaScript project file:

const Zesty = require('zestyio-api-wrapper')

Instantiation

You can get the Zesty.io token and instance ZUID for your instance from the Zesty.io manager. Go to the "Editor" section, and click on the "External Editing" button to display the values for your Zesty.io instance.

const token = 'PRIVATE_TOKEN_FROM_ZESTYIO' // Keep in env file not in code
const instanceZUID = '8-b0a6c2b192-xkgt38' // ZUID of the Zesty.io Cloud Content Instance on which to make requests
 
const zesty = new Zesty(instanceZUID, token)

You can optionally enable API request and error logging by setting one or both of the logErrors and logResponses flags:

const zesty = new Zesty(
  instanceZUID,
  token,
  {
    logErrors: true,
    logResponses: true
  }
)

Usage

Response Object Format

Responses from the API will generally be delivered as objects which have the following form:

{ _meta:
   { timestamp: '2019-02-14T18:42:19.279094718Z',
     totalResults: 1,
     start: 0,
     offset: 0,
     limit: 1 },
  data: // Object or array of objects.
}

The content of data will be either an object (for endpoints that return one item) or an array containing zero or more objects (endpoints that can return multiple items will return an array regardless of how many items match the query).

Content Models and Fields

Retrieval of content models and model fields. See documentation:

Get all content models:

try {
  const res = await zesty.getModels()
} catch (err) {
  console.log(err)
}

Get a content model by ZUID:

try {
  const modelZUID = '6-...' // Model ZUIDs begin with 6
  const res = await zesty.getModel(modelZUID)
} catch (err) {
  console.log(err)
}

Get all fields for a content model:

try {
  const modelZUID = '6-...'
  const res = await zesty.getFields(modelZUID)
} catch (err) {
  console.log(err)
}

Get a specific field by field ZUID for a content model:

try {
  const modelZUID = '6-...'
  const fieldZUID = '12-...' // Field ZUIDs begin 12
  const res = await zesty.getField(modelZUID, fieldZUID)
} catch (err) {
  console.log(err)
}

Content Items

Content items are always accessed relative to their model, so a model ZUID is required for each call. See the documentation here.

Get all content items for a model:

try {
  const modelZUID = '6-...' // Model ZUIDs begin with 6
  const res = await zesty.getItems(modelZUID)
  console.log(res)
} catch (err) {
  console.log(err)
}

Get a specific content item by ZUID:

try {
  const modelZUID = '6-...'
  const itemZUID = '7-...' // Item ZUIDs begin with 7
  const res = await zesty.getItem(modelZUID, itemZUID)
} catch (err) {
  console.log(err)
}

Create a content item:

try {
  const modelZUID = '6-...'
  const res = await zesty.createItem(modelZUID, {
      data: { // Values here will depent on content model
          text_field_one: 'hello', 
          text_field_two: 'world'
      },
      meta: {
          createdByUserZUID: '5-...', // User ZUIDs begin with 5
          contentModelZUID: modelZUID
      },
      web: {
        canonicalTagMode: 1,
        metaDescription: 'This is the description.',
        metaKeywords: 'these,are,some,keywords',
        metaLinkText: 'This is the meta link text.',
        metaTitle: 'This is the meta title.'
      }
  })
} catch (err) {
  console.log(err)
}

This will return the ZUID of the created item in the response.

Save a content item:

try {
  const modelZUID = '6-...'
  const itemZUID = '7-...'
 
  const res = await zesty.saveItem(modelZUID, itemZUID, {
      data: {
          text_field_one: 'updated',
          text_field_two: 'item'
      },
      meta: {
          masterZUID: itemZUID
      }
  })
} catch (err) {
  console.log(err)
}

Get all versions for a specific content item by ZUID:

try {
  const modelZUID = '6-...'
  const itemZUID = '7-...'
  const res = await zesty.getItemVersions(modelZUID, itemZUID)
} catch (err) {
  console.log(err)
}

Get a specific version of a content item by version ZUID:

try {
  const modelZUID = '6-...'
  const itemZUID = '7-...'
  const res = await zesty.getItemVersion(modelZUID, itemZUID, 2)
} catch (err) {
  console.log(err)
}

Get all publishing records for a specific content item by ZUID:

try {
  const modelZUID = '6-...'
  const itemZUID = '7-...'
  const res = await zesty.getItemPublishings(modelZUID, itemZUID)
} catch (err) {
  console.log(err)
}

Get specific publishing record by publishing ZUID for a content item:

try {
  const modelZUID = '6-3029e8-x4cbhh'
  const itemZUID = '7-9cd6d2cdf9-spmszq'
  const publishingZUID = '18-7c02d25-rpzw1v' // Publishing ZUIDs begin with 18
  const res = await zesty.getItemPublishing(modelZUID, itemZUID, publishingZUID)
} catch (err) {
  console.log(err)
}

Views

The wrapper allows CRUD on Zesty.io view files. See documentation here:

Get all views:

(returns an array of view objects)

try {
  const res = await zesty.getViews()
} catch(err) {
  console.log(err)
}

Get a view by ZUID:

try {
  const viewZUID = '11=...' // View ZUIDS begin with 11
  const res = await zesty.getView(viewZUID)
} catch(err) {
  console.log(err)
}

Create a view (snippet):

const fileName = 'navigation-snippet'
const code = 'my view content'
const payload = {
  code: code,
  fileName: fileName
}
 
try {
  const res = await zesty.createView(payload)
} catch (err) {
  console.log(err)
}

Create a view (endpoint):

const fileName = '/special-endpoint.json'
const code = JSON.stringify({ foo: 'bar' })
const payload = {
  code: code,
  type: 'ajax-json',
  fileName: fileName
}
 
try {
  const res = await zesty.createView(payload)
} catch (err) {
  console.log(err)
}

Save a view:

This will only save the updated view, and will not publish it.

const viewZUID = '11-...'
const code = 'my view content'
const payload = {
  code: code
}
 
try {
  const res = await zesty.saveView(viewZUID, payload)
} catch (err) {
  console.log(err)
}

Save and publish a view:

Both saves the updated view and publishes it.

const viewZUID = '11-...'
const code = 'my view content'
const payload = {
  code: code
}
 
try {
  const res = await zesty.saveAndPublishView(viewZUID, payload)
} catch (err) {
  console.log(err)
}

Get all versions of a view:

const viewZUID = '11-...'
 
try {
  const res = await zesty.getViewVersions(viewZUID)
} catch(err) {
  console.log(err)
}

Get a specific version of a view:

const viewZUID = '11-...'
const viewVersionNumber = 2
 
try {
  const res = await zesty.getViewVersion(viewZUID, viewVersionNumber)
} catch(err) {
  console.log(err)
}

Scripts

CRUD on Zesty.io script files. See documentation here.

Get all scripts:

(returns an array of script objects).

try {
  const res = await zesty.getScripts()
} catch(err) {
  console.log(err)
}

Get a script by ZUID:

try {
  const scriptZUID = '10-...' // Script ZUIDs begin with 10
  const res = await zesty.getScript(scriptZUID)
} catch(err) {
  console.log(err)
}

Create a script:

const fileName = 'my-script.js'
const code = "alert('hello world');"
const payload = {
  code: code,
  fileName: fileName,
  type: 'text/javascript'
}
 
try {
  const res = await zesty.createScript(payload)
} catch (err) {
  console.log(err)
}

Save a script:

Change the contents of a script, while retaining the filename.

const scriptZUID = '10-...'
const code = "alert('hello world');"
const payload = {
  code: code
}
 
try {
  const res = await zesty.saveScript(scriptZUID, payload)
} catch (err) {
  console.log(err)
}

Get all versions of a script:

try {
  const scriptZUID = '10-...'
  const res = await zesty.getScriptVersions(scriptZUID)
} catch(err) {
  console.log(err)
}

Get a specific version of a script:

try {
  const scriptZUID = '10-...'
  const versionNumber = 1
  const res = await zesty.getScriptVersion(scriptZUID, versionNumber)
} catch(err) {
  console.log(err)
}

Stylesheets

CRUD on Zesty.io stylesheet files. See documentation here.

Get all stylesheets:

try {
  const res = await zesty.getStylesheets()
} catch(err) {
  console.log(err)
}

Get a stylesheet by ZUID:

try {
  const stylesheetZUID = '10-...' // Stylesheet ZUIDs begin with 10
  const res = await zesty.getStylesheet(stylesheetZUID)
} catch(err) {
  console.log(err)
}

Create a stylesheet:

const fileName = 'styles.less'
const code = ".myClass { text-align: left; }"
const stylesheetType = 'text/less' // Can also use text/css or text/scss
const payload = {
  code: code,
  fileName: fileName,
  type: stylesheetType
}
 
try {
  const res = await zesty.createScript(payload)
} catch (err) {
  console.log(err)
}

Save a stylesheet:

Change the contents of a stylesheet, while retaining the filename and file type.

const stylesheetZUID = '10-...'
const code = ".anotherClass { text-align: center; }"
 
const payload = {
  code: code
}
 
try {
  const res = await zesty.saveStylesheet(stylesheetZUID, payload)
} catch (err) {
  console.log(err)
}

Get all versions of a stylesheet:

try {
  const stylesheetZUID = '10-...'
  const res = await zesty.getStylesheetVersions(stylesheetZUID)
} catch(err) {
  console.log(err)
}

Get a specific version of a stylesheet:

try {
  const stylesheetZUID = '10-...'
  const stylesheetVersion = 1
  const res = await zesty.getStylesheetVersion(stylesheetZUID, stylesheetVersion)
} catch(err) {
  console.log(err)
}

Head Tags

CRUD on <head> tags (for example meta tags, stylesheet link tags, script tags that go in the head area of an HTML document). Allows setting of tags at a per item (refered to as Resource ZUID in the documentation) level. See documentation here.

Get all head tags:

try {
  const res = await zesty.getHeadTags()
} catch (err) {
  console.log(err)
}

Get a single head tag by ZUID:

const headTagZUID = `21-...` // Head Tag ZUIDs begin with 21
 
try {
  const res = await zesty.getHeadTag(headTagZUID)
} catch (err) {
  console.log(err)
}

Create a head tag:

See the documentation for the full range of options.

const resourceZUID = '7-...' // A content item
 
try {
  // Create a script tag to load a script only when rendering the view for the
  // content item whose ZUID is in resourceZUID
 
  let res = await zesty.createHeadTag({
    type: 'script',
    attributes: {
      src: 'https://mydomain.com/libs/library.js'
    },
    resourceZUID: resourceZUID
  })  
 
  // Create a meta 'generator' tag added in the head only when rendering the
  // view for the content item whose ZUID is in resourceZUID
 
  res = await zesty.createHeadTag({
    type: 'meta',
    attributes: {
      generator: 'This is a test'
    },
    resourceZUID: resourceZUID
  })  
 
  // Create a 'link' tag to load a CSS file from a specified URL only when 
  // rendering the view for the content item whose ZUID is in resourceZUID.
 
  res = await zesty.createHeadTag({
    type: 'link',
    attributes: {
      rel: 'stylesheet',
      href: 'https://mydomain.com/css/mystylesheet.css'
    },
    resourceZUID: resourceZUID
  })
} catch (err) {
  console.log(err)
}

Update an existing head tag by ZUID:

See the documentation for the full range of options.

const headTagZUID = `21-...` // Head Tag ZUIDs begin with 21
const resourceZUID = '7-...' // A content item
 
// Update an existing head tag to be a script loaded from its URL only 
// when rendering the view for the content item whose ZUID is in resourceZUID.
 
try {
  const res = await zesty.saveHeadTag(
    headTagZuid,
    {
      type: 'script',
      attributes: {
        src: 'https://mydomain.com/libs/another-library.js'
      },
      resourceZUID: resourceZUID
    }
  )
} catch (err) {
  console.log(err)
}

Delete a single head tag by ZUID:

const headTagZUID = `21-...` // Head Tag ZUIDs begin with 21
 
try {
  const res = await zesty.getSiteHead()
} catch (err) {
  console.log(err)
}

Site Head Entries

Get all site head entries:

See API documentation here.

try {
  const res = await zesty.deleteHeadTag(headTagZUID)
} catch (err) {
  console.log(err)
}

Navigation Entries

Get all navigation entries:

Returns all items needed to build navigation for a management interface. See the API documentation here.

try {
  const res = await zesty.getNav()
} catch (err) {
  console.log(err)
}

Audit Trail

Provides methods to retrieve and filter audit trail entries. See documentation here.

Get all audit trail entries:

try {
  const res = await zesty.getAuditTrailEntries()
} catch (err) {
  console.log(err)
}

Get a specific audit trail entry by ZUID:

const auditZUID = '15-...' // Audit trail entry ZUIDs begin with 15
 
try {
  const res = await zesty.getAuditTrailEntries(auditZUID)
} catch (err) {
  console.log(err)
}

Get audit trail entries having specific properties:

const filterProps = {
  // Object keys can be:
  // order
  // dir
  // start_date
  // end_date
  // limit
  // page
  // action
  // affectedZUID
  // userZUID
  // See documentation for examples.
}
 
try {
  res = await zesty.searchAuditTrailEntries({
      limit: 5,
      order: 'created',
      dir: 'desc'
  })
} catch(err) {
  console.log(err)
}

Examples for each filtering parameter can be found in the API documentation.

Instance Settings

Get all instance settings:

try {
  const res = await zesty.getSettings()
} catch(err) {
  console.log(err)
}

Get instance setting by setting ID:

try {
  const settingID = 5
  const res = await zesty.getSetting(settingID)
} catch(err) {
  console.log(err)
}

Media Management Calls

Media Bins

Get all media bins:

try {
  const binsResponse = await zesty.getMediaBins()
  const firstBin = binsResponse.data[0]
  const firstBinId = firstBin.id
} catch (err) {
  console.log(err)
}

Abbreviated response format:

{ 
  message: 'Bin',
  status: 'OK',
  code: 200,
  data:[ 
    { 
      id: '<Bin ZUID>',
      name: '<Bin Name>',
      created_at: '2018-07-09T21:50:27.000Z',
      deleted_at: null,
      default: true 
    },
    ...
  ] 
}

Get media bin by ID:

try {
  const binId = 'media bin ID'
  const binResponse = await zesty.getMediaBin(binId)
} catch (err) {
  console.log(err)
}

Abbreviated response format:

{ 
  message: 'Bin',
  status: 'OK',
  code: 200,
  data: [ 
    { 
      id: '<Bin ZUID>',
      name: '<Bin Name>',
      created_at: '2018-07-09T21:50:27.000Z',
      deleted_at: null
    } 
  ] 
}

Update media bin by ID:

(Allows for bin name to be updated).

const binId = 'media bin ID'
 
try {
  const binUpdateResponse = await zesty.updateMediaBin(binId, {
    name: 'New Name'
  })
} catch (err) {
  console.log(err)
}

Abbreviated response format:

{ 
  message: 'Bin <Bin ZUID> updated',
  status: 'OK',
  code: 200,
  data: [ 
    { 
      id: '<Bin ZUID>', 
      name: 'New Name' 
    } 
  ] 
}

Media Groups (Folders)

Get all media groups in a bin:

const binId = 'media bin ID'
 
try {
  const binGroupsResponse = await zesty.getMediaGroups(binId)
} catch (err) {
  console.log(err)
}

Abbreviated response format:

{ 
  message: 'Folder',
  status: 'OK',
  code: 200,
  data: [ 
    { 
      id: '<Group ZUID>',
      bin_id: '<Bin ZUID>',
      group_id: '<Parent Group ZUID>',
      name: '<Group Name>' 
    },
    ...
  ] 
}

Get media group by ID:

const groupId = 'media group ID'
 
try {
  const groupResponse = await zesty.getMediaGroup(groupId)
} catch (err) {
  console.log(err)
}

Abbreviated response format:

{ 
  message: 'group',
  status: 'OK',
  code: 200,
  data: [ 
    { 
      id: '<Group ZUID>',
      bin_id: '<Bin ZUID>',
      group_id: '<Parent Group ZUID>',
      name: '<Group Name>',
      groups: [],
      files: [ 
        { 
          id: '<File ZUID>',
          bin_id: '<Bin ZUID>',
          group_id: '<Group ZUID>',
          filename: '<Filename>',
          title: '<File Display Name>',
          url: '<URL to file>',
          created_by: null,
          created_at: '2018-10-22T23:13:24.000Z',
          updated_at: '2018-10-22T23:13:40.000Z',
          deleted_at: null
        },
        ... 
      ] 
    } 
  ] 
}

Create media group:

const binId = 'media bin ID'
const groupId = 'parent group ID - optional'
const name = 'new group name - optional defaults to new folder'
 
try {
  const createGroupResponse = await zesty.createMediaGroup({
    bin_id: binId,
    group_id: groupId,
    name: name
  })
} catch (err) {
  console.log(err)
}

Abbreviated response format:

{ 
  message: 'Created folder <Group Name>',
  status: 'OK',
  code: 201,
  data: [ 
    { 
      id: '<Group ZUID>',
      bin_id: '<Bin ZUID>',
      group_id: '<Parent Group ZUID>',
      name: '<Group Name>',
      type: 'group' 
    } 
  ] 
}

Update media group by ID:

const groupId = 'group ID to update'
const parentGroupId = 'parent group ID - optional'
const name = 'new group name - optional'
 
try {
  const updateGroupResponse = await zesty.updateMediaGroup(
    groupId,
    {
      group_id: parentGroupId,
      name: name
    }
  )
} catch (err) {
  console.log(err)
}

Abbreviated response format:

{ 
  message: 'Updated group <Group Name>',
  status: 'OK',
  code: 200,
  data: [ 
    { 
      id: '<Group ZUID>',
      name: '<Group Name>',
      group_id: '<Parent Group ZUID>' 
     } 
  ] 
}

Delete media group by ID:

const groupId = 'group ID to delete'
 
try {
  const deleteGroupResponse = await zesty.deleteMediaGroup(groupId)
} catch (err) {
  console.log(err)
}

Abbreviated response format:

{ 
  message: 'Deleted group <Group ZUID>',
  status: 'OK',
  code: 200 
}

Media Files

Get all media files in a bin:

const binId = 'media bin ID'
 
try {
  const binFilesResponse = await zesty.getMediaFiles(binId)
} catch (err) {
  console.log(err)
}

Abbreviated response format:

{ 
  message: 'Group',
  status: 'OK',
  code: 200,
  data: [ 
    { 
      id: '<File ZUID>',
      bin_id: '<Bin ZUID>',
      group_id: '<Group ZUID>',
      filename: '<File name>',
      title: '<File display name>',
      url: '<URL to file>',
      created_by: null,
      created_at: '2018-10-22T23:13:24.000Z',
      updated_at: '2018-10-22T23:13:40.000Z',
      deleted_at: null,
    },
    ...
  ] 
}

Get media file by ID:

const fileId = 'media file ID'
 
try {
  const fileResponse = await zesty.getMediaFile(fileId)
} catch (err) {
  console.log(err)
}

Abbreviated response format:

{ 
  message: 'Files',
  status: 'OK',
  code: 200,
  data: [ 
    { 
      id: '<File ZUID>',
      bin_id: '<Bin ZUID>',
      group_id: '<Group ZUID>',
      filename: '<File name>',
      title: '<File display name>',
      url: '<URL to file>',
      created_by: null,
      created_at: '2018-10-22T23:13:24.000Z',
      updated_at: '2018-10-22T23:13:40.000Z',
      deleted_at: null
    } 
  ] 
}

Create (upload) media file:

const fs = require('fs')
const fileName = 'test.jpg'
const stream = fs.createReadStream(`/path/to/${fileName}`)
const fileType = 'image/jpeg'
const title= = 'A Media Item'
const binId = 'media bin ID'
const groupId = 'media group ID, use bin ID for root folder in bin'
 
try {
  const createFileResponse = await zesty.createMediaFile(
    binId,
    groupId,
    fileName,
    title,
    fileType,
    stream
  )
} catch (err) {
  console.log(err)
}

Abbreviated response format:

{ 
  message: 'File uploaded',
  status: 'Created',
  data: [ 
    { 
      id: '<File ZUID>',
      bin_id: '<Bin ZUID>',
      group_id: '<Group ZUID>',
      filename: '<File name>',
      title: '<File display name>',
      url: '<URL to file>',
      type: 'file' 
    } 
  ],
  code: 201 
}

Update media file by ID:

(Allows ability to change file name, display title, group that the file is in).

const fileId = 'media file ID'
const newName = 'newname.jpg - optional'
const newTitle = 'New Title - optional'
const newGroup = 'new group ID - optional'
 
try {
  const updateFileResponse = await zesty.updateMediaFile(
    fileId,
    {
      filename: newName,
      title: newTitle,
      group_id: newGroup
    }
  )
} catch (err) {
  console.log(err)
}

Abbreviated response format:

{ 
  message: 'Updated file <File Name>',
  status: 'OK',
  code: 200,
  data: [ 
    { 
      id: '<File ZUID>',
      group_id: '<Group ZUID>',
      title: '<File Display Title>',
      filename: '<File Name>',
      url: '<URL to file>' 
    } 
  ] 
}

Delete media file by ID:

const fileId = 'media file ID'
 
try {
  const deleteFileResponse = await zesty.deleteMediaFile(fileId)
} catch (err) {
  console.log(err)
}

Abbreviated response format:

{ 
  message: '1 files deleted and purging',
  status: 'OK',
  code: 200 
}

Keywords

install

npm i zestyio-api-wrapper

weekly downloads

version

0.1.12

license

GNU

homepage

github.com

repository

github

last publish

3 days ago

collaborators

Test with RunKit

Report a vulnerability

zestyio-api-wrapper

Zesty.io Node API Wrapper

Installation

Instantiation

Usage

Response Object Format

Content Models and Fields

Content Items

Views

Scripts

Stylesheets

Head Tags

Site Head Entries

Navigation Entries

Audit Trail

Instance Settings

Media Management Calls

Media Bins

Media Groups (Folders)

Media Files

Keywords

install

Downloadsweekly downloads

version

license

homepage

repository

last publish

collaborators

weekly downloads