API

Anura API

  • Format: Anura always responds in JSON (except for thumbnails/downloads) using UTF-8. JSONP is supported through the callback parameter.
  • Location: Based on the name of the dispatcher (usually anura) there are two services
    • server.com/anura/node.do - answers inqueries about structures (folders/keywords/collections) and searches.
    • server.com/anura/asset.do - answers inqueries about a specific asset (details, thumbnails, downloads).
  • Cache: Results are always cached (except searches) on the server side for a configurable amount of time (default: 1h). Use the flush parameter to force a refresh
  • Empty responses usually indicate that a fatal error has occurred. Check celum's ims.log in such cases for more information.

Note: the foo[]-notation for GET parameters is not supported by the server, use foo=1&foo=2 instead

Required parameters are marked in bold

Changes in 2.0

Version 2 was developed for CELUM 5 - while it tries to be as compatible as possible, not all features are available on both platforms. The most notable change in version 2 is that every response is delivered in an envelope, e.g.

{
    "version": 2,
    "status": 200,
    "data": {/* result, same as in 1.x */}
}

This means that you always get an answer, even if something went wrong. The status code (which can't be obtained with JSONP otherwise) is also provided and set to 200 in the HTTP response when the callback parameter is set (otherwise nothing will arrive in your callback function). Additionally the API version is specified and and an optional message-parameter may be present when an error has occurred.

General parameters

  • callback (string) - response will be wrapped in a callback function for JSONP (e.g. using callback=myfunc the response is myfunc([...]) instead of just [...])
  • locale (string) - language you'd like to get the response in (e.g. "de"). Availability of languages is determined by celum, leave blank for default language.
  • flush (boolean) - "true" will flush the cache, useful for forcing an update but has a negative impact on the performance. Use with caution.
  • cache (boolean) - "false" will bypass the cache for this request

node.do

Node structure

  • tree (int) - celum ID of the desired root node - supports multiple root IDs like tree=1&tree=5 to construct a virtual root node. Set to -1 to get all root nodes (enforces with_root=true; since 1.7).
  • kind (int) - Type of container (101 = folder, 102 = object collection, 103 = keyword in 1.x, see tabconfiguration.xml in 2.x)
  • depth (int) - how many levels of the structure should be loaded (useful for lazy loading in big structures) - not fully loaded nodes are indicated by having an empty "children" attribute. Values below 1 will load the entire structure (default)
  • with_root (boolean) - include the root node itself in the result - probably only useful in combination with a virtual root node
  • asset_count (boolean) - calculates the number of assets contained within each node. (slow in 1.x! - don't use on big trees without lazy loading)
    • noderef (boolean) - include assets in count that reference this node in a node referencing information field (since 2.1)
    • recursive (boolean) - include noderefs recursively in count (since 2.1)

Example:

[GET] server.com/node.do?tree=4123&kind=103&depth=2

[{
  "id": 2620,
  "type": 103,
  "name": "Color",
  "children":[
    {"id": 2791, "type": 103, "name": "Greyscale"},
    {"id": 2792, "type": 103, "name": "RGB"},
    {"id": 2793, "type": 103, "name": "CMYK"}
  ]
}]

Note: You can construct virtual root nodes by specifying multiple tree parameters from which that node should be constructed, i.e. tree=4123&tree=1337&tree=42

Content of nodes

  • id (int) - celum ID of the container
  • kind (int) - Type of container (101 = folder, 102 = object collection, 103 = keyword in 1.x, see tabconfiguration.xml in 2.x)
  • alt_name (int) - Information field ID to use as an alternative name (because asset names aren't localized). Note that this will make loading a bit slower.
  • recursive (boolean) - Load assets from sub-nodes as well and present them on the top level (since 2.0, acts like the enabled keyword thesaurus in 1.x)
  • noderef (boolean) - Consider node referencing information field assignments as direct assignments ("Navigation Context" in the UI)

Example:

[GET] server.com/anura/node.do?kind=101&id=7&alt_name=2

[
  {"id": 1337,"type": 1, "name": "pic_12_001.jpg", "alt_name": "This is an example"},
  {"id": 1338,"type": 2, "name": "api_demo.odt", "alt_name": "Demonstration of the API"}
]

Note: type is 1=image, 2=document, 3=video, 4=audio, 5=text, 0=unknown

Search

  • search (string) - full text search, e.g. "ponies"
  • search_folder (int) - celum ID of the folder to restrict the search to, DEPRECATED in 2.x -> use search_node
  • search_keyword (int[]) - celum ID of the keyword to restrict the search to, multiple keywords (AND search) may be specified using search_keyword=1&search_keyword=2, DEPRECATED in 2.x -> use search_node
  • search_ (boolean) - default is true
    • search_images - show images in result,
    • search_documents - show documents in result
    • search_videos - show videos in result
    • search_audios - show audios in result
    • search_others - show others in result
  • search_extensions (string[]) - search by file extension, e.g. search_extensions=png,eps
  • search_uploaded_after (string) - restrict results to assets uploaded after this date
  • search_uploaded_before (string) - restrict results to assets uploaded before this date
  • search_modified_after (string) - restrict results to assets modified after this date
  • search_modified_before (string) - restrict results to assets modified before this date
  • search_limit (int) - limit the number of search results (limited by the server's maxSearchResults)
  • search_infofield (int,mixed...[]) - search by information field value, syntax: ,[,...] - e.g. search_infofield=7,true

An information field query provides the possible values and properties where applicable (dropdowns, boolean, nodereference)

1.x only
  • search_min_bytes (long) - minimum asset size in bytes
  • search_max_bytes (long) - maximum asset size in bytes
  • search_min_width (int) - minimum asset width in pixel
  • search_max_width (int) - maximum asset width in pixel
  • search_min_height (int) - minimum asset height in pixel
  • search_max_height (int) - maximum asset height in pixel
  • search_node_or_mode and search_node_recursive from 2.x have been backported but can only affect keywords
  • search_order (int) - order search results (ID = 0; NAME = 1; SIZE = 2; UPLOADDATE = 3; ORIGINAL_FILENAME = 4; UPLOADBY = 5; LASTMODIFIED = 9)
  • search_order_seq (int) - order search results ascending (0) or descending (1)
2.x only
  • search_or_mode (boolean) - connect different search terms with OR, default is AND
  • search_asset_type (int) - asset type IDs (e.g. 3000,4000)
  • search_node (long[]) - node IDs to restrict the search to, e.g. search_node=123&search_node=987
  • search_node_recursive (boolean) - search in subnodes as well, default is true
  • search_facets (int) - return facets (if a facet-provider is installed), 0 = disabled (default), 1 = only facets, 2 = facets and assets, (since 2.6)
  • sort_order (string) - order search results (id, name, uploaddate, lastmodified, extension, assettype, score) or 1.x syntax where applicable
  • sort_order_seq (string) - order search results ascending (asc) or descending (desc) or 1.x syntax
  • paginate (int) - Number of assets to load, i.e. page size. This will also add a total count to the response (since 2.1)
  • page (int) - Which page of the pagination to load, i.e. from (page-1)paginate to pagepaginate (since 2.1)

Example:

[GET] server.com/anura/node.do?search_folder=4&search=ponies

[
  {"id": 42, "type": 1, "name": "ponies_on_a_farm.jpg"},
  {"id": 1337, "type": 2,"name": "My favorite ponies.xls"}
]

Result controls

These parameters are applicable to node content and search queries

  • extended (boolean) - Provide extended info about each asset (size in bytes, modified as timestamp, extension, pages, valid_until as timestamp), default is false
  • sort_order (string) - order search results (id, name, uploaddate, lastmodified, extension, assettype) (since 2.2)
  • sort_order_seq (string) - order search results ascending (asc) or descending (desc) (since 2.2)
  • paginate (int) - Number of assets to load, i.e. page size. This will also add a total count to the response (since 2.1)
  • page (int) - Which page of the pagination to load, i.e. from (page-1)paginate to pagepaginate (since 2.1)
  • limit (int) - Limits the number of results (or total count) returned, even if there are actually more assets (since 2.4)

Top Downloads

  • top (int) - max. number of assets to show (e.g. for "Top 10 downloads": top = 10, max. is 100)
  • days (int) - scope to the last X days (default is 30, max. is 365)

Example:

[GET] server.com/anura/node.do?top=15&days=7

[
  {"id": 1337, "type": 1, "name": "pic_12_001.jpg", "alt_name": "This is an example", "downloads": 9001},
  {"id":1338, "type": 2, "name": "api_demo.odt", "alt_name": "Demonstration of the API", "downloads": 1234}
]

About

  • about (boolean) - request system information (such as versions, languages etc.) Example:

[GET] your.server.com/anura/node.do?about=true

{
    "apiVersion": 2.0,
    "cacheTimeSeconds": 3600,
    "celumVersion": "5.10.3",
    "containerLanguages": ["en", "de", "fr"],
    "customFieldLanguages": ["en", "de", "fr"],
    "defaultLanguage": "en",
    "guiLanguages": ["en", "de", "fr"],
    "infoField": "",
    "maxSearchResults": 256,
    "supportEmail": "support@brix.ch",
    "userId": 2
}

asset.do

Previews

There are two kinds of previews available (Content-Disposition=inline, Content-Type=image/jpeg). How big those are may be configured, default is: thumb 200x200, preview 1024x1024 (maximum)

  • thumb or preview (int) - celum ID of the asset you want a thumb/preview of
    • page (int) - which page to get a preview of (zero-based, only for documents)
    • big (boolean) - request a bigger thumb (separate parameter for backwards compatibility, since 1.7)
  • play or stream (int) - celum ID of the video asset to be played back, play will use celum's player and stream will return the raw file
    • autoplay (boolean) - will start playing the requested file automatically
    • nojs (boolean) - don't use video-js (uses plain HTML5 tags, look/functionality depends on browser)

Example: [GET] your.server.com/anura/asset.do?thumb=1337&img=a.jpg

Note: The &img=a.jpg part does absolutely nothing but has been added because some browsers might like to have a file extension at the end

Downloading

Download Formats

First of all you'll need to get a list of the available download formats (should be done once on application launch):

[GET] your.server.com/anura/asset.do?downloadformats=1

[
  {"name":"Originalformat","icon":"../img/icons/32x32/originalImageTargetFormat.gif","id":6, "position":1},
  {"name":"Web Format","icon":"../img/icons/32x32/webImageTargetFormat.gif","id":5, "position":2}
]

Notes:

  • the icons are relative to the anura URL used and are the same ones that celum uses internally (and despite the folder name they probably have a different size)
  • there might be a "url" parameter, which indicates that the anura user doesn't have the permission to download the asset directly. Send the user to that URL instead of the default one, which triggers an interactive celum login.

As of version 2.0 you can also query the available download formats by file extension(s), e.g.:

[GET] your.server.com/anura/asset.do?downloadformats=jpg

[
  {"id": ​1, "name": "Original file", "description": "Download original file", "icon": "../../images/download-formats/dark/big/orig.png"}, 
  {"id": ​2, "name": "Web JPG", "description": "JPG 1024x1024", "icon": "../../images/download-formats/dark/big/web.png"}
]

Multiple extensions are supported as well (intersection):

[GET] your.server.com/anura/asset.do?downloadformats=jpg,mp4

[{"id": ​1, "name": "Original file", "description": "Download original file", "icon": "../../images/download-formats/dark/big/orig.png"}]

As of version 2.2, you can query the available download formats for an asset:

[GET] your.server.com/anura/asset.do?downloadformats_for=1337&locale=en

{"name": "0100181.psd", "extension": "psd", "type": 1, "formats": [
    {"id": 1, "name": "Original file", "description": "Download original file", "icon": "../../images/download-formats/dark/big/orig.png"},
    {"id": 2, "name": "Web JPG", "description": "Download JPG optimized for web", "icon": "../../images/download-formats/dark/big/web.png" }
]}

As of version 2.6, you'll get some additional infos about enabled DownloadFormatInterceptors (see CMA)

  • resizeable -> paperFormatDownloadFormatInterceptor is enabled
  • editable -> imageEditorDownloadFormatInterceptor is enabled
  • message -> messageBoxDownloadFormatInterceptor is enabled

[GET] your.server.com/anura/asset.do?downloadformats=jpg

[{"id": 8, "name": "User Definable", "description": "Allows the user to choose the size", "icon": "../../images/download-formats/dark/big/orig.png", "resizeable": true, "editable": false, "message": false}]
Download

Knowing the download format IDs you can then trigger a download:

  • download (int[]) - celum ID of the asset to be downloaded
  • format (int) - celum ID of the download format to be used (see above)
  • forcezip (boolean) - force even single asset downloads to be delivered in a ZIP-file

You can download multiple files at once in a ZIP by specifying more than one download, e.g. download=42,1337,7 (the old notation "download=1&download=2" is still supported)

Example: [GET] your.server.com/anura/asset.do?download=42&format=6

This will stream the file directly to the browser with Content-Disposition=attachment.

As of version 2.0, you can specify a download formats per asset (colon-separated, overrides the format parameter) with download=:, e.g. download=1337:6 or download=42:1,1337:6,7:1

As of version 2.6, you can add additional download format options (if a DownloadFormatInterceptor is present), e.g. download=1337:8:width=100;height=100;unit=px

Known parameters:

  • width or UserTargetSizeWidth (float) - Width for the paperFormatDownloadFormatInterceptor
  • height or UserTargetSizeHeight (float) - Height for the paperFormatDownloadFormatInterceptor
  • unit or UserTargetSizeUnit (String) - Unit for the paperFormatDownloadFormatInterceptor - one of "mm", "inch" or "px" (default)
  • locale is set implicitly through the regular locale parameter. Has no known effect unless you use a custom API File Name Resolver.

Details

  • details (int) - celum ID of the asset you want to get detailed information about
  • details_infofields (boolean) - whether to include information fields in the response, default is true
  • details_keywords (boolean) - whether to include keywords (name -> path) in the response, default is false
  • details_keyword_paths (boolean) - whether to include complete keyword paths in the response, default is true
  • details_keywords_list (boolean) - whether to include a list of keyword objects in the response, default is false
  • details_links (boolean) - whether to include related objects (aka links, up to 5), default is false
  • details_downloads (boolean) - whether to add the available download formats for this file, default is true (since 2.1)

Example:

[GET] your.server/anura/asset.do?details=1337&locale=en

{
"name":"gnampf.jpg",
"general_title":"Object Details",
"general":{
    "Creation date": "Jul 18, 2013 2:51:56 PM",
    "File size": "205 KB",
    "File extension":"jpg",
    "Size": "1049 x 697 Pixels",
    "DPI": "72",
    "Graphic type": "Raster",
    "ICC-Profile":"Adobe RGB (1998)"
},
"infofields_title":"Information Fields",
"infofields":[
    {"id": "info_108", "name": "Copyright Required", "value": "No", "type": "Boolean"},
    {"id": "info_121", "name": "Copyright Information", "value": "Some copyright text", "type": "TextArea"},
],
"keywords_title":"Keywords",
"keywords":{
    "RGB":"/Color/",
    "Basel":"/Location/Europe/Switzerland/"
}

[GET] your.server/anura/asset.do?details=1337&locale=en&details_keyword_paths=true&details_keyword_list=true&links=true

{
/* ...snip... */
"keyword_paths": [
    "/Color/RGB",
    "/Location/Europe/Switzerland/Basel"
],
"keyword_list": [
    {id: "123", name: "RGB", path: "/Color"},
    {id: "456", name: "Basel", path: "/Location/Europe/Switzerland"}
],
"links":[
    {id: 55456, type: 2, name: "license_agreement.pdf"}
]
}

As of 2.1 the response will also contain the available download formats in the downloads field (same as if you'd request downloadformats= separately) and node referencing information fields have an additional values with the individual nodes (instead of just the "bla, foo"-string):

{
/* ...snip... */
"infofields": [
    {
        "id": "info_125",
        "name": "Type of Document",
        "type": "NodeReference",
        "value": "First value, Second value",
        "values": [
            {"id": "noderef_2702", "name": "First value",  "value": "2702", "type": "103", "info": "/Path/To/Value"}
            {"id": "noderef_4702", "name": "Second value", "value": "4702", "type": "103", "info": "/Path/To/Value"}
        ]
    }
],
"downloads": [
    {"id": 1,"name": "Original file", "description": "Download original file", "icon": "../../images/download-formats/dark/big/orig.png"},
    {/* snip */}
]
}

Information fields

Get information about the nature of an information field

  • infofield (long or list of long) - celum ID(s) of the information field(s) you want to query (or -1 to get all, since 2.7). Dropdown fields will also report all available values.

Note: type is 0 = text, 1 = number, 2 = date, 3 = node reference (since 2.0), 4 = checkbox, 5 = dropdown

Example:

[GET] server.com/anura/asset.do?infofield=7

{"name": "Image source", "description": "Where you got it from", "type": 0}

Dropdown fields also declare the possible values:

{..., "values":[{"name": "Fotolia", "id": 4},{"name": "Getty Images", "id": 5},{"name": "DigitalVision", "id": 6}]}

Node referencing fields declare additional settings:

{..., "root_node": 1100, "show_root": false, max_selections": -1]}

Translation

Access any translated string available in celum

  • string (string[]) - the message key you'd like to get translated. Multiple strings can be requested using string=first.key&string=second.key

Example:

[GET] server.com/anura/asset.do?string=detailview.title&string=detailview.infobox.noinfo

{"detailview.title":"Object Details","detailview.infobox.noinfo":"No information available"}