Zesty.io Node API Wrapper
Deprecation Notice - Posted March 14th 2020 |
---|
Updates and support to the zesty node api wrapper will continue until June, 1st 2021 |
The zesty node api wrapper package will remain available through NPM with a decrecation warning. |
Please migrate your scripts and services the Zesty.io Node SDK https://www.npmjs.com/package/@zesty-io/sdk |
Thank you, Reach out to support at zesty dot io with any questions. |
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 = ;
Instantiation
You can get the Zesty.io token and instance ZUID for your instance from the Zesty.io manager, or by using the authentication functionality in the wrapper. At this time, authentication through the wrapper does not support user accounts using 2FA authentication.
Authenticating using the Wrapper
This wrapper now includes functionality to authenticate a user by their email address and password, returning a token that can then be used to make API calls. This should be used, for scenarios such as building a tool that runs periodically and authenticates to Zesty.io in order to perform some task: uploading content or retrieving audit log information for example.
We do not recommend that you put values for email address and password in your code or source control system - treat these as secrets and use environment variables or some other mechanism to ensure that their values aren't stored in the code nor committed to source control.
In the following example, we're assuming the use of environment variables:
const ZestyAuth = ; try const email = processenvZESTY_USER_EMAIL; const password = processenvZESTY_USER_PASSWORD; const zestyAuth = ; const token = await zestyAuth; catch e console;
If the correct credentials are configured in the environment variables ZESTY_USER_EMAIL
and ZESTY_USER_PASSWORD
, the above snippet will log the user in and return a token that can then be used to instantiate the API wrapper.
Obtaining a Token Manually from the Zesty Editor
You can also obtain a token manually by logging into your Zesty.io instance, then going to the "Editor" section in the manager application. From there, click on the "External Editing" button which displays the ZUID and token for your instance.
Instantiating the Wrapper
Once you have obtained a token, you can instantiate the API wrapper as follows:
const token = "PRIVATE_TOKEN_FROM_ZESTYIO"; // Obtain using one of the methods described aboveconst instanceZUID = "8-..."; // ZUID of the Zesty.io Cloud Content Instance on which to make requests const 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 = instanceZUID token logErrors: true logResponses: true;
Note that the user whose login generated the token will need to have permissions to access the particular Zesty.io instance that the wrapper is instantiated with. As access to instances is also associated with roles, the user will need to have the appropriate role set in Zesty.io in order to be allowed to perform various API calls.
Validating a Token
Tokens are currently session based. This means that they will expire after a period of inactivity. To check whether a token is valid you can use the verifyToken
method in the auth class:
try const zestyAuth = ; // token has been obtained from zestyAuth.login... const isTokenGood = await zestyAuth; catch e console;
If this returns true
, your token is good to make API calls. If false
, you should re-authenticate and get a new token.
Usage
Response Object Format
Responses from the API will generally be delivered as objects having 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).
Error Response Format
Responses for error cases will generally be delivered as objects having the following form:
reason: 'Textual description' statusCode: 401 // HTTP response code from API, 400, 401, 500 etc error: 'Something is wrong' // null or string or object with error detail
Content Models and Fields
Retrieval of content models and model fields. See documentation:
Get all content models:
try const res = await zesty; catch err console;
Get a content model by ZUID:
try const modelZUID = "6-..."; // Model ZUIDs begin with 6 const res = await zesty; catch err console;
Get all fields for a content model:
try const modelZUID = "6-..."; const res = await zesty; catch err console;
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; catch err console;
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; console; catch err console;
Get a specific content item by ZUID:
try const modelZUID = "6-..."; const itemZUID = "7-..."; // Item ZUIDs begin with 7 const res = await zesty; catch err console;
Create a content item:
try const modelZUID = "6-..."; const res = await zesty; catch err console;
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; catch err console;
Get all versions for a specific content item by ZUID:
try const modelZUID = "6-..."; const itemZUID = "7-..."; const res = await zesty; catch err console;
Get a specific version of a content item by version ZUID:
try const modelZUID = "6-..."; const itemZUID = "7-..."; const res = await zesty; catch err console;
Delete a content item by ZUID:
try const modelZUID = "6-..."; const itemZUID = "7-..."; const res = await zesty; catch err console;
Example response:
_meta: timestamp: '2019-02-20T23:25:37.556Z' totalResults: 1 start: 0 offset: 0 limit: 1 message: 'Item deleted' data: {}
Note: this response format may change in future.
Item Publishing and Unpublishing
Publish a version of an item immediately:
try const modelZUID = "6-..."; const itemZUID = "7-..."; const versionNumber = 1; const res = await zesty; catch err console;
The expected response looks like this:
_meta: timestamp: '2019-02-20T23:28:25.487Z' totalResults: 1 start: 0 offset: 0 limit: 1 message: 'Published' data: item_zuid: '7-...' version_zuid: '9-...' version_num: '1'
Note: this response format may change in future.
Unpublish a published item immediately:
try const modelZUID = "6-..."; const itemZUID = "7-..."; const publishingZUID = "18-..."; const res = await zesty; catch err console;
The expected response looks like this:
_meta: timestamp: '2019-02-20T23:46:14.423Z' totalResults: 1 start: 0 offset: 0 limit: 1 message: 'Entry updated' data: {}
Note: this response format may change in future.
Get all publishing records for a specific content item by ZUID:
try const modelZUID = "6-..."; const itemZUID = "7-..."; const res = await zesty; catch err console;
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; catch err console;
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; catch err console;
Get a view by ZUID:
try const viewZUID = "11=..."; // View ZUIDS begin with 11 const res = await zesty; catch err console;
Create a view (snippet):
const fileName = "navigation-snippet";const code = "my view content";const payload = code: code fileName: fileName; try const res = await zesty; catch err console;
Create a view (endpoint):
const fileName = "/special-endpoint.json";const code = JSON;const payload = code: code type: "ajax-json" fileName: fileName; try const res = await zesty; catch err console;
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; catch err console;
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; catch err console;
Get all versions of a view:
const viewZUID = "11-..."; try const res = await zesty; catch err console;
Get a specific version of a view:
const viewZUID = "11-...";const viewVersionNumber = 2; try const res = await zesty; catch err console;
Scripts
CRUD on Zesty.io script files. See documentation here.
Get all scripts:
(returns an array of script objects).
try const res = await zesty; catch err console;
Get a script by ZUID:
try const scriptZUID = "10-..."; // Script ZUIDs begin with 10 const res = await zesty; catch err console;
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; catch err console;
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; catch err console;
Save and publish a script:
Both saves the updated script and publishes it.
const scriptZUID = "10-...";const code = "alert('hello again');";const payload = code: code; try const res = await zesty; catch err console;
Get all versions of a script:
try const scriptZUID = "10-..."; const res = await zesty; catch err console;
Get a specific version of a script:
try const scriptZUID = "10-..."; const versionNumber = 1; const res = await zesty; catch err console;
Stylesheets
CRUD on Zesty.io stylesheet files. See documentation here.
Get all stylesheets:
try const res = await zesty; catch err console;
Get a stylesheet by ZUID:
try const stylesheetZUID = "10-..."; // Stylesheet ZUIDs begin with 10 const res = await zesty; catch err console;
Create a stylesheet:
const fileName = "styles.less";const code = ".myClass { text-align: left; }";const stylesheetType = "text/less"; // Can also use text/css or text/scssconst payload = code: code fileName: fileName type: stylesheetType; try const res = await zesty; catch err console;
Create a stylesheet and show transpiler errors:
const fileName = "styles.less";const code = ".myClass { text-align: left; }";const stylesheetType = "text/less"; // Can also use text/css or text/scssconst payload = code: code fileName: fileName type: stylesheetType;const showError = true; try const res = await zesty; catch err console;
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; catch err console;
Save a stylesheet and show transpiler errors:
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;const showError = true; try const res = await zesty; catch err console;
Save and publish a stylesheet:
Both saves the updated stylesheet and publishes it.
const stylesheetZUID = "10-...";const code = ".anotherClass { background-color: #ff0000; }";const payload = code: code; try const res = await zesty; catch err console;
Save and publish a stylesheet and show transpiler errors:
Both saves the updated stylesheet and publishes it.
const stylesheetZUID = "10-...";const code = ".anotherClass { background-color: #ff0000; }";const payload = code: code;const showError = true; try const res = await zesty; catch err console;
Get all versions of a stylesheet:
try const stylesheetZUID = "10-..."; const res = await zesty; catch err console;
Get a specific version of a stylesheet:
try const stylesheetZUID = "10-..."; const stylesheetVersion = 1; const res = await zesty; catch err console;
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; catch err console;
Get a single head tag by ZUID:
const headTagZUID = `21-...`; // Head Tag ZUIDs begin with 21 try const res = await zesty; catch err console;
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; // 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; // 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; catch err console;
Update an existing head tag by ZUID:
See the documentation for the full range of options.
const headTagZUID = `21-...`; // Head Tag ZUIDs begin with 21const 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; catch err console;
Delete a single head tag by ZUID:
const headTagZUID = `21-...`; // Head Tag ZUIDs begin with 21 try const res = await zesty; catch err console;
Site Head Entries
Get all site head entries:
See API documentation here.
try const res = await zesty; catch err console;
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; catch err console;
Audit Trail
Provides methods to retrieve and filter audit trail entries. See documentation here.
Get all audit trail entries:
try const res = await zesty; catch err console;
Get a specific audit trail entry by ZUID:
const auditZUID = "15-..."; // Audit trail entry ZUIDs begin with 15 try const res = await zesty; catch err console;
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; catch err console;
Examples for each filtering parameter can be found in the API documentation.
Instance Settings
Get all instance settings:
try const res = await zesty; catch err console;
Get instance setting by setting ID:
try const settingID = 5; const res = await zesty; catch err console;
Media Management Calls
Media Bins
Get all media bins:
try const binsResponse = await zesty; const firstBin = binsResponsedata0; const firstBinId = firstBinid; catch err console;
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; catch err console;
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; catch err console;
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; catch err console;
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; catch err console;
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; catch err console;
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; catch err console;
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; catch err console;
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; catch err console;
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; catch err console;
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 = ;const fileName = "test.jpg";const stream = fs;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; catch err console;
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; catch err console;
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; catch err console;
Abbreviated response format:
message: '1 files deleted and purging' status: 'OK' code: 200