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
.