NAV Navbar
JavaScript curl
  • Asset Delivery API reference
  • Authentication
  • Sharetribe Flex SDK
  • Caching
  • Querying asset data
  • 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": {
        "exampleString": "example asset data",
        "exampleArray": ["item1", "item2"]
      },
      "meta": {
        "version": "abcd"
      }
    }
    

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