Asset Delivery API reference

Assets in a Sharetribe marketplace are pieces of configuration data and content that client applications use and display. The Asset Delivery API provides efficient read-only access to the marketplace's assets.

Authentication

Example request

$ curl https://cdn.st-api.com/v1/assets/pub/[CLIENT_ID]/a/latest/example/asset.json

Requests to the Asset Delivery API are authenticated with a client ID of a valid Marketplace API application. The client ID is given as part of the request URL path and is not sent as a separate header. All Asset Delivery API request endpoints have the following base URL: https://cdn.st-api.com/v1/assets/pub/[CLIENT_ID]/.

Sharetribe SDK

const sharetribeSdk = require('sharetribe-flex-sdk');

const sdk = sharetribeSdk.createInstance({
  clientId: '<Your Client ID here>'
});

The most convenient way to access marketplace asset data is using the Sharetribe SDK for JavaScript. The SDK provides convenience methods for retrieving assets by alias or by version and can automatically form the correct API URLs for each request. It also handles any HTTP redirects that the API may respond with. Be sure to use the latest available version of the SDK (but at least version >= v1.19.0).

Caching

The Asset Delivery API is backed by a content delivery network that caches asset data in order to ensure optimal performance. Each HTTP response of the Asset Content API contains an appropriate Cache-Control header. The maximum caching times depend on whether the marketplace is a live, development or a test environment, and on whether the access is by concrete version or by latest alias. The following table summarizes the possible caching times:

Marketplace environment	Access	Cache time
live	by version	up to 1 year
live	by alias	up to 5 minutes
dev	by version	up to 1 year
dev	by alias	up to 10 seconds
test	by version	up to 1 year
test	by alias	up to 10 seconds

Note that access to asset data using the automatically managed latest alias is also subject to the same caching rules. Therefore, for example, in a live marketplace it may take up to 5 minutes for a change in asset data to be visible to end users.

Some API responses may specify shorter cache times. Client applications are advised to observe the Cache-Control header.

Further, Asset Delivery API responses contain an ETag HTTP header and the API supports conditional requests using the If-None-Match request header. Clients that support caching can make use of those to avoid having to download asset data unnecessarily. If the requested data has not changed, the API responds with HTTP status code 304 (Not Modified).

When the Sharetribe SDK is used in a web browser environment, the Asset Delivery API works out of the box with the browser's cache, allowing for optimal efficiency.

Querying asset data

Response format

The Asset Delivery API responses have application/json content type. Responses that contain data (i.e. have HTTP status code 200 and not 301 or 304) have a JSON document as the body.

Single asset response

Example response for a single asset

{
  "data": {
    "config": {
      "marketplaceName": "Marketplace name here",
      "categories": [
        "Renting",
        "Selling"
      ]
    },
    "images": {
      "heroBackground": {
        "_ref": {
          "id": "f51d406b-cf63-4ab7-a3b5-cf3c74f265a0",
          "type": "imageAsset"
        }
      }
    }
  },
  "included": [
    {
      "id": "f51d406b-cf63-4ab7-a3b5-cf3c74f265a0",
      "type": "imageAsset",
      "attributes": {
        "assetPath": "/path/to/image.jpeg",
        "variants": {
          "scaled": {
            "width": 1500,
            "height": 1200,
            "url": "https://www.example.com/image/af08671a-54e8-47be-bc19-cbd6478efded"
          },
          "cropped": {
            "width": 900,
            "height": 900,
            "url": "https://www.example.com/image/f51d406b-cf63-4ab7-a3b5-cf3c74f265a0"
          }
        }
      }
    }
  ],
  "meta": {
    "version": "ncxp8C1Q4Z_piy9rmC9tDA"
  }
}

The response body of a single asset request has the following keys:

Key	Description
data	(JSON object) The asset data.
included	(JSON array) A list of one or more referred assets.
included.*.id	(uuid) Reference identifier that maps the included asset to a reference in `data`.
included.*.type	(string) Type of the referred asset. Currently only `imageAsset` is supported.
included.*.attributes	(JSON object) Reference attributes depending on the reference type. For an `imageAsset` reference the attributes are `assetPath` that holds the path to the referred asset and `variants` object that lists the available variants of an image.
meta	(JSON object) Metadata about the asset.
meta.version	(string) The asset tree version for the requested data. Read more about asset versioning here.

Multiple assets response

Example response for multiple assets

{
  "data": [
    {
      "id":  "bf98a0b4-7789-457e-8e61-a7cc32cc2602",
      "type": "jsonAsset",
      "attributes": {
        "assetPath": "/example/asset1.json",
        "data": {
          "config": {
            "marketplaceName": "Marketplace name here",
            "categories": [
              "Renting",
              "Selling"
            ]
          },
          "images": {
            "heroBackground": {
              "_ref": {
                "id": "f51d406b-cf63-4ab7-a3b5-cf3c74f265a0",
                "type": "imageAsset"
              }
            }
          }
        }
      }
    },
    {
      "id":  "5e9279c3-2d47-4447-aa8a-4c0d87ac6895",
      "type": "jsonAsset",
      "attributes": {
        "assetPath": "/example/asset2.json",
        "data": {
          "exampleString": "...",
          "exampleArray": ["..."]
        }
      }
    }
  ],
  "included": [
    {
      "id": "f51d406b-cf63-4ab7-a3b5-cf3c74f265a0",
      "type": "imageAsset",
      "attributes": {
        "assetPath": "/path/to/image.jpeg",
        "variants": {
          "scaled": {
            "width": 1500,
            "height": 1200,
            "url": "https://www.example.com/image/af08671a-54e8-47be-bc19-cbd6478efded"
          },
          "cropped": {
            "width": 900,
            "height": 900,
            "url": "https://www.example.com/image/f51d406b-cf63-4ab7-a3b5-cf3c74f265a0"
          }
        }
      }
    }
  ],
  "meta": {
    "version": "abcd"
  }
}

The response body of a request for multiple assets has the following keys:

Key	Description
data	(array) An array of JSON objects containing the asset data.
data[].id	(string) UUID of the asset, unique within version.
data[].type	(string) Type of the asset, e.g. `"imageAsset"` or `"jsonAsset"`.
data[].attributes	(JSON object) Object containing asset data.
data[].attributes.assetPath	(string) The absolute path of the asset.
data[].attributes.data	(JSON object) The asset data.
included	(JSON array) A list of one or more referred assets.
included.*.id	(uuid) Reference identifier that maps the included asset to a reference in `data`.
included.*.type	(string) Type of the referred asset. Currently only `imageAsset` is supported.
included.*.attributes	(JSON object) Reference attributes depending on the reference type. For an `imageAsset` reference the attributes are `assetPath` that holds the path to the referred asset and `variants` object that lists the available variants of an image.
meta	(JSON object) Metadata about the asset.
meta.version	(string) The asset tree version for the requested data. Read more about asset versioning here.

Asset references

Assets may contain references to other assets. An asset references appear as JSON objects that have a single key, _ref. The value of _ref is a JSON object with two attributes: id and type. A top level attribute included holds a list of asset reference descriptions that can be identified by the combination of id and type attributes. Included assets are normalized, so a single included asset can be referred multiple times from the source asset with the same id and type. See the example response for a full example of asset references.

At the moment, only references with type imageAsset are supported.

`imageAsset` resource format

Example resource

{
  "id": "f51d406b-cf63-4ab7-a3b5-cf3c74f265a0",
  "type": "imageAsset",
  "attributes": {
    "assetPath": "/path/to/image.jpeg",
    "variants": {
      "scaled": {
        "width": 1500,
        "height": 1200,
        "url": "https://www.example.com/image/af08671a-54e8-47be-bc19-cbd6478efded"
      },
      "cropped": {
        "width": 900,
        "height": 900,
        "url": "https://www.example.com/image/f51d406b-cf63-4ab7-a3b5-cf3c74f265a0"
      }
    }
  }
}

The imageAsset resource represents data about an image asset.

Attribute	Description
assetPath	(string) Full absolute path of the asset.
variants	(object) Object containing data about image variants. The keys are the variant names.
variants.*.width	(integer) The actual width in pixels of the image after the transformation corresponding to the variant.
variants.*.height	(integer) The actual height in pixels of the image after the transformation corresponding to the variant.
variants.*.url	(string) A URL which can be used to fetch the image data. The URL must not be considered as immutable. Client applications that cache URLs should do so as indicated by the API response, i.e. by observing the `Cache-Control` header, or for a month at most.

Note that the variants for an image depend on the data in the JSON asset that refers to the image and cannot be changed at query time. For example, JSON assets that represent data for Pages have image variants defined according to the page asset schema.

Single asset by `latest` alias

HTTP request

GET /v1/assets/pub/[CLIENT_ID]/a/latest/[ASSET_PATH]

Example request

$ curl https://cdn.st-api.com/v1/assets/pub/CLIENT_ID/a/latest/example/asset.json

sdk.assetByAlias({ path: "example/asset.json", alias: "latest" }).then(res => {
  // res.data contains the response data as JSON object
});

Example response

{
  "data": {
    "exampleString": "example asset data",
    "exampleArray": ["item1", "item2"]
  },
  "meta": {
    "version": "abcd"
  }
}

// res.data
{
  data: {
    exampleString: "example asset data",
    exampleArray: ["item1", "item2"]
  },
  meta: {
    version: "abcd"
  }
}

Query the data for a given asset using the latest alias. The latest alias is automatically managed by Sharetribe and references the latest asset tree version.

Read more about asset versioning and the latest alias here.

The asset path is specified as part of the URL path after the version alias latest.

Multiple assets by `latest` alias

HTTP request

GET /v1/assets/pub/[CLIENT_ID]/a/latest/[PATH_PREFIX/]?assets=ASSET1[,ASSET2,...]

Example request

$ curl https://cdn.st-api.com/v1/assets/pub/CLIENT_ID/a/latest/?assets=example/asset1.json,example/asset2.json
# or using a path prefix
$ curl https://cdn.st-api.com/v1/assets/pub/CLIENT_ID/a/latest/example/?assets=asset1.json,asset2.json

sdk.assetsByAlias({
  paths: ["example/asset1.json", "example/asset2.json"],
  alias: "latest"
}).then(res => {
  // res.data contains the response data as an array of JSON objects.
  // Note the SDK parameter is 'paths'. The SDK automatically builds
  // the correct API request URL with appropriate PATH_PREFIX and
  // list of 'assets'.
});

Example response

{
  "data": [
    {
      "id":  "bf98a0b4-7789-457e-8e61-a7cc32cc2602",
      "type": "jsonAsset",
      "attributes": {
        "assetPath": "/example/asset1.json",
        "data": {
          "exampleString": "example asset data",
          "exampleArray": ["item1", "item2"]
        }
      }
    },
    {
      "id":  "5e9279c3-2d47-4447-aa8a-4c0d87ac6895",
      "type": "jsonAsset",
      "attributes": {
        "assetPath": "/example/asset2.json",
        "data": {
          "exampleString": "...",
          "exampleArray": ["..."]
        }
      }
    }
  ],
  "meta": {
    "version": "abcd"
  }
}

// res.data
{
  data: [
    {
      id:  "bf98a0b4-7789-457e-8e61-a7cc32cc2602",
      type: "jsonAsset",
      attributes: {
        assetPath: "/example/asset1.json",
        data: {
          exampleString: "example asset data",
          exampleArray: ["item1", "item2"]
        }
      }
    },
    {
      id:  "5e9279c3-2d47-4447-aa8a-4c0d87ac6895",
      type: "jsonAsset",
      attributes: {
        assetPath: "/example/asset2.json",
        data: {
          exampleString: "...",
          exampleArray: ["..."]
        }
      }
    }
  ],
  meta: {
    version: "abcd"
  }
}

Query the data for a list of assets using the latest alias. The latest alias is automatically managed by Sharetribe and references the latest asset tree version.

Read more about asset versioning and the latest alias here.

The assets are specified via the query parameter assets as a comma-separated list of paths. If all assets share a common path prefix, it can optionally be specified as part of the URL path after the version alias latest, in which case the assets paths would need to be relative to that prefix.

The response may include the data for none, some or all assets being queried depending on whether they were found or not. The API response will have HTTP status code 200 in either case, and the client is responsible for handling partial data in the response.

The assets are returned in lexical order of their assetPath.

Single asset by version

HTTP request

GET /v1/assets/pub/[CLIENT_ID]/v/[VERSION]/[ASSET_PATH]

Example request

$ curl https://cdn.st-api.com/v1/assets/pub/CLIENT_ID/v/abcd/example/asset.json

sdk.assetByVersion({ path: "example/asset.json", version: "abcd" }).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "exampleString": "example asset data",
    "exampleArray": ["item1", "item2"]
  },
  "meta": {
    "version": "abcd"
  }
}

// res.data
{
  data: {
    exampleString: "example asset data",
    exampleArray: ["item1", "item2"]
  },
  meta: {
    version: "abcd"
  }
}

Query the data for a given asset using a concrete asset tree version.

The asset path is specified as part of the URL path after the version.

HTTP redirects

When querying asset data by version, the API may respond with an HTTP redirect (status code 301) in cases when the requested asset has not changed in the requested asset tree version. The Location header in the HTTP response specifies appropriate URL to access the given asset using the version in which it changed most recently before the requested version. Since asset versions are immutable, the redirect can be a permanent one (301) and the redirect response itself may be cached. This mechanism helps avoid unnecessary data transfer in cases when a given asset changes more rarely than other assets.

The Sharetribe SDK automatically handles redirect responses, so that the application always receives the asset data through the SDK call return value. However, client applications that do not use the SDK must follow the redirect in order to retrieve the asset data.

For example, suppose assets a.json and b.json both change in version v1 and then only asset a.json changes a second time in version v2. Then, if asset b.json is requested using version v2, the API responds with redirect to URL for accessing that asset using version v1.

Multiple assets by version

HTTP request

GET /v1/assets/pub/[CLIENT_ID]/v/[VERSION]/[PATH_PREFIX/]?assets=ASSET1[,ASSET2,...]

Example request

$ curl https://cdn.st-api.com/v1/assets/pub/CLIENT_ID/v/abcd/?assets=example/asset1.json,example/asset2.json
# or using a path prefix
$ curl https://cdn.st-api.com/v1/assets/pub/CLIENT_ID/v/abcd/example/?assets=asset1.json,asset2.json

sdk.assetByVersion({
  paths: ["example/asset1.json", "example/asset2.json"],
  version: "abcd"
}).then(res => {
  // res.data contains the response data as an array of JSON objects.
  // Note the SDK parameter is 'paths'. The SDK automatically builds
  // the correct API request URL with appropriate PATH_PREFIX and
  // list of 'assets'.
});

Example response

{
  "data": [
    {
      "id":  "bf98a0b4-7789-457e-8e61-a7cc32cc2602",
      "type": "jsonAsset",
      "attributes": {
        "assetPath": "/example/asset1.json",
        "data": {
          "exampleString": "example asset data",
          "exampleArray": ["item1", "item2"]
        }
      }
    },
    {
      "id":  "5e9279c3-2d47-4447-aa8a-4c0d87ac6895",
      "type": "jsonAsset",
      "attributes": {
        "assetPath": "/example/asset2.json",
        "data": {
          "exampleString": "...",
          "exampleArray": ["..."]
        }
      }
    }
  ],
  "meta": {
    "version": "abcd"
  }
}

// res.data
{
  data: [
    {
      id:  "bf98a0b4-7789-457e-8e61-a7cc32cc2602",
      type: "jsonAsset",
      attributes: {
        assetPath: "/example/asset1.json",
        data: {
          exampleString: "example asset data",
          exampleArray: ["item1", "item2"]
        }
      }
    },
    {
      id:  "5e9279c3-2d47-4447-aa8a-4c0d87ac6895",
      type: "jsonAsset",
      attributes: {
        assetPath: "/example/asset2.json",
        data: {
          exampleString: "...",
          exampleArray: ["..."]
        }
      }
    }
  ],
  meta: {
    version: "abcd"
  }
}

Query the data for a list of assets using a concrete asset tree version.

The assets are specified via the query parameter assets as a comma-separated set of paths. If all assets share a common path prefix, it can optionally be specified as part of the URL path after the version, in which case the assets paths would need to be relative to that prefix.

The assets are returned in lexical order of their assetPath.

HTTP redirects

When querying asset data by version, the API may respond with an HTTP redirect (status code 301) in cases when the most-recently modified asset in the list has not changed in the requested asset tree version. The Location header in the HTTP response specifies appropriate URL to access the data using the asset tree version that matches the version of the most-recently modified asset. Since asset versions are immutable, the redirect can be a permanent one (301) and the redirect response itself may be cached. This mechanism helps avoid unnecessary data transfer when a given list of assets don't change frequently.

For example, suppose there are three assets a.json, b.json and c.json in the tree version v1. b.json changes in version v2 and c.json in version v3. Then, if assets a.json and b.json are requested using version v3, the API responds with redirect to a URL for accessing those assets using the tree version v2, the version in which those assets were most-recently modified.

Asset Delivery API reference

Authentication

Sharetribe SDK

Caching

Querying asset data

Response format

Single asset response

Multiple assets response

Asset references

imageAsset resource format

Single asset by latest alias

Multiple assets by latest alias

Single asset by version

HTTP redirects

Multiple assets by version

HTTP redirects

`imageAsset` resource format

Single asset by `latest` alias

Multiple assets by `latest` alias