XML API (deprecated)

The use of the API described in this article has been deprecated. Asset Bank provides a more comprehensive REST API . More details can be found here .

The API functionality allows external applications to connect to Asset Bank to perform searches and retrieve assets.

NOTE: The API is an Enterprise Level feature. Please contact us to ensure you are licensed to use this.

Configuration options
The API functionality can be restricted to only allow connections from certain servers (based on their IP address). This option should be used when the Asset Bank server has access to the internet to prevent unauthorised requests. If required the API functionality can be configured so that Asset Bank allows connections from any server however this should only be used if the Asset Bank server is within a private network. The API functionality can also be configured so that when retrieving an asset a unique filename is always used at the destination it is being copied to. This means that if two assets have the same filename they will never be overwritten at the destination.

The setting for this are:

api-enabled=

api-remote-download-destination-filenames-unique=

api-restrict-by-ip=

(set to true or false)

api-allowed-ip-addresses=

(comma separated list of ip addresses)

Search API
The search API can be used to perform searches in Asset Bank and obtain the results in XML format. The XML extract below gives an example of what the search results might look like:

<search_results>

<result id="10100" thumbnailUrl="http://assetbankurl/servlet/display?file=filename.jpg">
<attribute label="Title">
My First Image
</attribute>
<attribute label="Description">
Some descriptive text about my first image
</attribute>
<attribute label="Date Created">
01/01/2001
</attribute>
</result>

<result id="10101" thumbnailUrl="http://assetbankurl/servlet/display?file=filename2.jpg">
<attribute label="Title">
My Second Image
</attribute>
<attribute label="Description">
Some descriptive text about my second image
</attribute>
<attribute label="Date Created">
02/02/2002
</attribute>
</result>

</search_results>

To perform a search using the API you call the URL http://asset-bank-server/asset-bank/api/search with the required search parameters. The search parameters that can be passed are similar to those passed to the search action in Asset Bank so that is often a good place to start when identifying the parameters that you need to provide the API request. Searching for assets with a particular attribute value is a case of providing a parameter with the name attribute_<id> and a value specifying what you want to search for (<id> obviously needs to be replaced with the id of the attribute you want to search). In addition to attribute searches the other parameters that can be used when searching via the API are...

  • keywords
  • dateAddedLower
  • dateAddedUpper
  • dateModLower
  • dateModUpper
  • dateDownloadedLower
  • dateDownloadedUpper
  • assetIds - comma separated list of asset ids
  • filename
  • orientation - integer constant representing the desired orientation (1 = landscape, 2 = portrait, 3 = square, 0 = any)
  • descriptiveCategoryForm.categoryIds - comma separated list of category ids that assets should be in
  • permissionCategoryForm.categoryIds - comma separated list of access level ids that an asset should be in
  • includeImplicitCategoryMembers - true or false indicating whether sub category members should be returned
  • promoted - true, false or both
  • userId or username - specifies a user to constrain the search results to (i.e. returned results will be ones that the user in question has permission to see)

By default the search api returns assets in a paged fashion (defaulting to 100 assets per page). To select the page you would like to retrieve you need to provide a page=[pagenumber] parameter. The 100 asset default per page can be overridden with a parameter (i.e. pageSize=[requiredPageSize]). If you don't want to retrieve assets in a paged fashion you can set the api-page-size parameter in ApplicationSettings.properties to be blank (or 0) which will disable paging and return all matching results at once (Please Note: Making requests to Asset Bank for large result sets via the API will put a load on the server).

The search API returned XML contains attribute values for display attributes which are shown on the search results in Asset Bank by default. This set of attributes is specified in Admin > Attributes > Display Attributes.

If you wish to return values for all attributes please add the parameter ‘fullList=true‘ to the end of your request.

NOTE: the search will be performed significantly more quickly if quick=true is passed as parameter/value. However, only the 'Display Attributes' for 'search results' will be returned.

The ID that is returned for assets can be used to retrieve the asset file as explained below.

Retrieve API
The Asset Bank API functionality can be used to retrieve assets over the following protocols:
  • Local - transfer to a location on the server for access/download.
  • SCP - securely transfer the asset to a remote server
  • SFTP - transfer the asset with secure FTP
  • FTP - transfer the asset with regular FTP


Retrieving an asset is done by calling /api/remoteDownloadAsset. This is called with the following options:

  • transferMethod: Either local, scp, sftp or ftp
  • assetId: The ID of the asset to be downloaded (can be obtained by performing an API search)
  • uploadLocation: The path on the remote server to which the asset will be uploaded
  • filenameUnique: ‘true‘ if the destination filename should be unique as not to overwrite any existing files in the directory
  • format: The file extension of the target format to which the (image) asset is to be converted
  • height: The height in pixels of the converted image (required for images, ignored for non-images)
  • width: The width in pixels of the converted image (required for images, ignored for non-images)
  • jpegQuality: A number between 0.0 and 1.0 representing the quality if converting to jpeg format (ignored for non-images)
  • convertToRGB: ‘true‘ if the download process should include a colourspace conversion to RGB
  • maintainAspectRatio: ‘true‘ if the image aspect ratio should be preserved, in which case the provided height and width are treated as maximum values
  • upscale: ‘true‘ if up-scaling should be performed if the size specified exceeds the original image size
  • host: The sftp/ftp host to transfer files to
  • username: The sftp/ftp username
  • password: The sftp/ftp password
  • port: The sftp/ftp port

Was this article helpful?

Yes No

Thanks for your feedback!