Anura always responds in JSON using UTF-8 (application/javascript; charset=UTF-8), except for thumbnails (image/jpeg) and downloads (application/zip).
JSONP is supported through the callback parameter.
Non-JSON responses usually indicate that a fatal error has occurred outside of Anura's control. Check celum's ims.log/appserver.log in such cases for more information.
Based on the name of the dispatcher (usually anura) there are two services:
Results are always cached on the server side for a configurable amount of time (default: 1h). Use the flush parameter to force a refresh.
The responses have also been designed to behave well when using an additional caching reverse proxy or load balancer in front of the API and will always send the appropriate Cache-Control, Content-Type and Content-Disposition headers.
Parameters you should ignore include callback, and depending on you use case also token. Furthermore you may want to listen to the cache control parameters flush (invalidates the cache) and cache (circumvents the cache for this request).
The API is public by default (and by design), so no authentication is needed. It it however possible to require authentication (see tokenVerifier), in which case you MUST pass a token either via the parameter token (...&token=mytoken) or preferably through the Authentication header (Authentication: token mytoken), since 2.8.12.
Note that the foo[]-notation for GET parameters is not supported by the server, use foo=1&foo=2 instead.
Required parameters are marked in bold
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 an optional message-parameter may be present when an error has occurred.
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
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
123,searchterm searches for the term "searchterm" in the infofield 123123,42 searches for the number "42" in the infofield 123123,42,1337 searches for numbers between 42 and 1337 in the infofield 123123,2 searches for dropdown item #2 in the infofield 123123,false searches for "false" values in the infofield 123123,456,789 searches for nodes 456 or 789 in the infofield 123123,1970-01-01 _searches for the first of January 1970 in the infofield 123yyyy-MM-dd, dd.MM.yyyy or MM/dd/yyyy123,2019-01-01,2019-12-31 _searches for any day in 2019 in the infofield 123123,null,2019-12-31An information field query provides the possible values and properties where applicable (dropdowns, boolean, nodereference)
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"}
]These parameters are applicable to node content and search queries
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}
][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
}There are two kinds of previews available (Content-Disposition=inline, Content-Type=image/jpeg). How big those are may be configured, default is: thumb 250x240, preview 1024x1024 (maximum)
X-Pages with the number of pages that are known to exist.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
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:
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)
[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}]As of version 2.7, you can also request infofields alongside the download infos, just as you would with asset and container requests:
[GET] your.server.com/anura/asset.do?downloadformats_for=1337&locale=en&infofields=148,137
{"name": "0100181.psd", "extension": "psd", "type": 1, "formats": [/*... snip ...*/],
"infofields": {"148": "Example", "137": "Jan 1, 2020"},
"infofields_raw": {"148": {"en": "Example", "de": "Beispiel"}, "137": 1577833200000}}Sidenote: The reason there are two info-maps here is to maintain backwards compatibility, as "raw" was introduced later
As of version 2.8, you can also ask for multiple assets at once to get a map of id -> download-info:
[GET] your.server.com/anura/asset.do?downloadformats_for=42,1337&locale=en
{
"42": {"name": "0100181.psd", "extension": "psd", "type": 1, "formats": [/*... snip ...*/]},
"1337": {"name": "some.jpg", "extension": "jpg", "type": 1, "formats": [/*... snip ...*/]}
}As of version 2.9, you can also ask for asset versions in this request:
[GET] your.server.com/anura/asset.do?downloadformats_for=42,1337&locale=en&versions=true
{"name": "flag_of_the_earth.png", "extension": "png", "type": 1, "formats": [/*... snip ...*/],
"versions": [
{"version": 1, "name": "flag_of_the_earth_fixed.png", "date": "May 2, 2016, 3:52:37 PM", "date_raw": 1462197157361, "active": true}
{"version": 0, "name": "flag_of_the_earth.png", "date": "May 2, 2016, 7:58:45 AM", "date_raw": 1462175925468, "active": false}
]
}Knowing the download format IDs you can then trigger a download:
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 download formats per asset (colon-separated, overrides the format parameter) with download=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>x<height>{+-}<xoffset>{+-}<yoffset>, e.g. crop=1280×720+50+50 crops to a 1280x720px area with an offset of 50px from the top and left. (since 2.9)
+ as %2B\d+(\.\d+)?%?x\d+(\.\d+)?%?([+-]\d+){0,2}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 download fields (same as if you'd request downloadformats=
{
/* ...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 */}
]
}you can override the name of informationsfields if you don't like what informationfields.xml provides by specifying
anura.infofield.name.<infofield-id>=...in your message bundle. Same goes foranura.infofield.readerinfo.<infofield-id>=....
Get information about the nature of an information field
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]}Access any translated string available in celum
Example:
[GET] server.com/anura/asset.do?string=detailview.title&string=detailview.infobox.noinfo
{"detailview.title":"Object Details","detailview.infobox.noinfo":"No information available"}Here's a list of translation keys that are known to be used by Anura.
Allows the creation of PINs. Note that anura.1.createPinParentNodeId must be configured. since 2.9
Because of a bug in the PIN view, the URL is not copyable (or to be more precise, it only works once, because showpin.do changes to pinaccess.do, which in turn creates a scoped session). You may want to add
history.replaceState(null, null, 'showpin.do'+location.search);as a custom JS to your PIN page to fix this.
Example:
[GET] server.com/anura/pin.do?create=42,1337&title=Example
{"pin":"dC2n8QysqXIn","link":"https://server.com/pinaccess/showpin.do?pinCode=dC2n8QysqXIn","title":"Example"}© brix IT Solutions