Skip to main content
Version: 2.1.9

Asset Service API Specification

This page describes how to integrate with the Asset Service on a technical level. The Foundation API Guide provides a higher-level overview of assets.

REST Resources​

The Asset Service provides resources for managing and retrieving assets and their representations.

Asset​

Assets are templated content that can be dynamically resolved with specific input data. They enable the Banqup platform to deliver personalized and localized content, such as notifications, HTML pages, or plain text, by filling in placeholders within the templates.

An example of a JSON asset that uses JSONata expressions for dynamic content:

{
  "notification": {
    "title": "data.matchInfo.homeTeam & ' vs. ' & data.matchInfo.awayTeam",
    "body": "data.matchInfo.status"
  },
  "data": {
    "Nick": "data.user.nickname",
    "Room": "data.matchInfo.homeTeam & 'VS' & data.matchInfo.awayTeam"
  },
  "option": {
    "ttl": "data.defaults.ttl",
    "collapse": "$collapseKey",
    "priority": "$priorityOverride ? $priorityOverride : data.defaults.priority"
  }
}

This asset can then be resolved by providing input data, resulting in personalized content:

{
  "notification": {
    "title": "Portugal vs. Denmark",
    "body": "great match!"
  },
  "data": {
    "Nick": "Mario",
    "Room": "PortugalVSDenmark"
  },
  "option": {
    "ttl": 4800,
    "priority": "NORMAL"
  }
}

The Asset Service supports various asset types, including JSON, HTML, and plain text, each capable of using different templating languages like JSONata and Freemarker for dynamic content.

Representation​

Representations are the actual content files stored within the Asset Service. These can be any type of file, such as text documents, images, or templated content (like the assets described above). The Asset Service allows for the storage, retrieval, updating, and deletion of these representations.

Representations are accessed via their full path, which can include directories, allowing for a hierarchical organization of content.

Example: Retrieving a representation

If you have a representation stored at subdir/invoice.en-US.txt, retrieving it would return its raw content.

Working with Assets​

Retrieving Assets​

To retrieve an asset, you'll perform a GET request to the /core/asset/v1/assets/:asset endpoint. You can specify fallback content types and languages through Accept and Accept-Language headers, respectively, to ensure content negotiation delivers the most suitable representation.

For example, to retrieve an asset named asset/iam/onboarding/template.en-US.pushnotification.json:

GET /v1/assets/asset/iam/onboarding/template
Accept: application/btx-pushnotification+json, application/json
Accept-Language: en-GB, en

A successful response (HTTP 200) will return the raw, templated content of the asset.

Resolving Assets​

To resolve an asset (i.e., fill its placeholders with data), you'll perform a POST request to the /core/asset/v1/assets/:asset endpoint, providing the input data in the request body. This allows the Asset Service to process the asset's template and return the fully rendered content.

For example, to resolve the same asset with specific user and match information:

POST /v1/assets/asset/iam/onboarding/template.en-US.pushnotification.json
 Content-Type: application/json

{
  "user": {
    "nickname": "Mario"
  },
  "matchInfo": {
    "homeTeam": "Portugal",
    "awayTeam" : "Denmark",
    "status": "great match!"
  },
  "defaults": {
    "ttl": 4800,
    "priority": "NORMAL"
  }
}

A successful response (HTTP 200) will return the asset with all its placeholders resolved by the provided input data.

Managing Representations​

Retrieving Representations​

You can retrieve the content of a specific representation or list the contents of a directory using GET requests to the /core/asset/v1/representations/:path endpoint.

  • To retrieve the content of a file, provide its full path.
  • To list directory contents, append a trailing slash to the directory path (e.g., /v1/representations/subdir/).

A successful retrieve will return an HTTP 200 Ok response.

Uploading or Updating Representations​

To upload new content or update an existing representation, perform a PUT request to /core/asset/v1/representations/:path, providing the content in the request body with Content-Type: application/octet-stream.

A successful upload will return an HTTP 201 Created response. A successful update will return an HTTP 200 Ok response.

Deleting Representations​

To delete a representation or an entire directory, perform a DELETE request to /core/asset/v1/representations/:path.

  • To delete a representation, provide its full path.
  • To delete a directory, append a trailing slash to the directory path (e.g., /v1/representations/subdir/).

A successful deletion will return an HTTP 204 No Content response.

Security​

Access to asset retrieval, resolution, and representation management is controlled by specific security scopes. For instance, asset_retrieve is required to retrieve an asset, asset_resolve for resolving an asset, and representation_read and representation_write for managing representations. Permissions are typically granted through an OAuth security scheme.

Authentication​

Security Scheme Type:

oauth2

OAuth Flow (clientCredentials):

Scopes:

  • info: Scopes are endpoint-specific, see each endpoint for required scope.

OAuth Flow (authorizationCode):

Scopes:

  • info: Scopes are endpoint-specific, see each endpoint for required scope.