Calling the Asset Delivery APIs

SDK methods

The Asset Delivery API allows retrieving the data of a single asset or a set of assets by alias or by version. The SDK has corresponding methods for each case.

assetByAlias()

The assetByAlias() method retrieves data for a single asset given a version alias. It takes an object as its argument and the object must contain:

• alias: currently must always have the value latest
• path: the path of the asset

For example:

const promise = sdk.assetByAlias({
  alias: "latest",
  path: "/content/translations.json"
});

assetByVersion()

The assetByVersion() method retrieves data for a single asset given a version string. It takes an object as its argument and the object must contain:

• version: the version string
• path: the path of the asset

For example:

const promise = sdk.assetByAlias({
  version: "ESz8ULLX68PiENQV",
  path: "/content/translations.json"
});

assetsByAlias()

The assetsByAlias() method retrieves data for a set of assets using the latest alias. It takes an object as its argument and the object must contain:

• alias: currently must always have the value latest
• paths: an array of asset paths

For example:

const promise = sdk.assetsByAlias({
  alias: "latest",
  paths: ["/content/translations.json", "/design/layout.json"]
});

Please note that the order of the returned assets may not be the same as the order of paths.

assetsByVersion()

The assetsByVersion() method retrieves data for a set of assets given a version string. It takes an object as its argument and the object must contain:

• version: the version string
• paths: an array of asset paths

For example:

const promise = sdk.assetsByAlias({
  version: "ESz8ULLX68PiENQV",
  paths: ["/content/translations.json", "/design/layout.json"]
});

Please note that the order of the returned assets may not be the same as the order of paths.

Responses

Calling any Asset Delivery API SDK method will always return a Promise. The value of the Promise differs whether the request was successful or error. In case of successful request the Promise will be fulfilled where as in case of error the Promise will be rejected.

Example:

const promise = sdk.assetByAlias({ alias: "latest", "path": "/content/translations.json" });

// Handle success response
promise.then(response => { console.log(response)} );

// Handle error response
promise.catch(response => { console.log(response)} );

Success response

A successful response will have the following format:

{
  status: 200,
  statusText: 'OK',
  data: // The data returned by the API. Object.
}

The response data key will not contain any data types beyond the data types that JSON supports, unlike responses returned by the SDK methods for the Marketplace API.

The API returns the data always in the following format:

{
  data: // Either an array of jsonAsset resources or just the data for a single asset
  meta: {} // Object containing metadata, such as version information
  included: [] // Array of included resources
}

See the Asset Delivery API reference for more information about the response data format. Note that the data inside the data key differs depending on whether a single asset or a set of assets are queried.

Error response

An error response will have the following format:

{
  status: <HTTP Status code, 4xx or 5xx>,
  statusText: <HTTP Status text>,
  data: // The data returned by the API, for example:
  {
    errors: [
      {
        status: <HTTP Status code, 4xx or 5xx>,
        code: // error code
        title: <HTTP Status text>,
        details: {
          // Additional details, not part of the public API.
        }
      }
    ]
  }
}

The error value is always an instanceof Error.

Please note that the content of the details is not part of the public API. This means that:

• You can use details for debugging and error tracking.
• You SHOULD NOT write production code that depends on the content of details.
• The content of details is not well specified and will change in the future.

Asset Delivery API documentation

For more information about the Asset Delivery API, see the reference documentation here.