Asset Delivery API reference

Assets in a Flex 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 Flex 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 Flex 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.17.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 production, development or a demo 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
prod	by version	up to 1 year
prod	by alias	up to 5 minutes
dev	by version	up to 1 year
dev	by alias	up to 10 seconds
demo	by version	up to 1 year
demo	by alias	up to 10 seconds

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 Flex 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

Example response

{
  "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 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 with 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.

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.

Asset data 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
});

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 Flex and references the latest asset tree version.

Asset data 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.

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 Flex 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.