The censhare server offers an API through HTTP calls, commonly called REST-API. Note that this API deliberately doesn’t always follow the “pure RESTful” representational state approach that is based on stateless web resources.

The API allows to access:

  • Assets and their metadata
    • by ID
    • by query expressed as URL matrix parameters, XML or JSON
  • Asset files
    • Previews, thumbnails, master files
  • Resources
    • Icons
    • Temporary files
  • XSLT Transformations

Notes:

  • Our XPath- and XSLT-Engine has many extensions that allow to create, update and transform assets, for example cropping a JPEG file. Transformations are usually used to implement this functionally.
  • In addition, the REST-API is extensible through Java scriptlet modules.

Restriction:

The censhare Server is designed as production system for interactive users or data hub through interfaces to various other system. The censhare-server is not designed and suitable to support a huge amount of requests through REST, for example as backend for a web site to deliver hundreds or thousands of pages per second. For this purpose, consider an Online channel web server or a Headless CMS (HCMS) to deliver your web content. Online channel and HCMS be scaled to handle huge amounts of content.

URLs and general access

Through the embedded web server of the censhare server, the REST-API can be called through standard HTTP:

http://{server}:{port}/ws/rest/service/assets/asset/id/105520/

Authentication is used and the results are limited to the access rights of the supplied user. https may be used as protocol for secured communication as well.

Note that from within the Java based desktop client, the existing client-server connection is used by specifying “censhare” as protocol instead of “http”.

censhare:///service/assets/asset/id/105520/

In the client, the placeholder ${asset-id} for the currently selected asset can be used:

REST with censhare protocol

Accessing assets

/service/assets/asset/id/{id}                             -- returns asset xml
/service/assets/asset/uuid/{uuid}                         -- returns asset xml
/service/assets/asset/key/{resource-key}                  -- returns asset xml for
                                                             resource key
/service/assets/short/{hash}                              -- performs mapping to complete
                                                             url and returns result
/service/assets/asset/id/{id}/version/{version}           -- returns asset xml
/service/assets/asset/id/{id}/currversion/{currversion}   -- returns asset xml
/service/assets/asset{matrix}                             -- returns asset xml
/service/assets/all{matrix}                               -- returns asset xmls
/service/assets/all;limit=2000                            -- return first 2000 asset xmls
/service/assets/all;limit=unlimited                       -- return asset xmls
/service/assets/all;                                      -- return per default first
                                                             1000 asset xmls
 + /element/target|actual/{idx}                           -- returns element xml
 + /element/target|actual/page/{page}                     -- returns element xml
   + /storage/{key}                                       -- returns storage xml
 + /storage/{key}                     -- returns storage xml
   + /file                            -- returns storage file (as stream)
   + /file/{cookie}                   -- returns storage file (as stream),
                                         arbitrary cookie that client may use for caching,
                                         e.g. asset modification date
   + /file-{cookie}                   -- returns storage file (as stream),
                                         arbitrary cookie that client may use for caching,
                                         e.g. asset modification date
 + /transform{matrix}                 -- perform xsl translation and return result
 + /transform/{key}                   -- perform xsl translation and return result,
                                         deprecated, use matrix parameters
 + /transform{matrix}/json            -- perform xsl translation and return result as JSON
   + /format/{format}                 -- deprecated, use matrix parameters
   + /file                            -- same as without file suffix: perform xsl
                                         translation and return result
   + /file/{cookie}                   -- allows to append a suffix
                                         (e.g. file name and extension) to the url
   + /file-{cookie}
 + /icon
   + /minsize
 + /preview
   + /file                            -- return the preview storage item or the icon if
                                         no storage item available
 + /model/xml                         -- return asset(s) as logical model in XML format
 + /model/json                        -- return asset(s) as logical model in JSON format
 + /model/transform{matrix}/xml       -- return asset(s) as logical model with a subsequent
                                         XSL transformation (result format is XML)
 + /model/transform{matrix}/json      -- return asset(s) as logical model with a subsequent
                                         XSL transformation (result format is JSON)

Accessing resources

/service/resources/icon/{key}      -- returns icon xml
+ /iconset/{name}|default
+ /background/bright|dark
+ /minSize/{size}
+ /file                           -- returns icon (as stream)
+ /file/{cookie}                  -- returns icon (as stream),
                                     arbitrary cookie that client may use for caching,
                                     e.g. modification date
+ /file-{cookie}                  -- returns icon (as stream),
                                     arbitrary cookie that client may use for caching,
                                     e.g. modification date
+ /file-cacheable/{cookie}        -- returns icon (as stream),
                                     arbitrary cookie that client may use for caching,
                                     e.g. modification date.
                                     The caching policy is set to "unlimited" in the
                                     response header for all resources,
                                     which are requested by this kind of URLs.

Examples

Accessing asset metadata

Syntax: assets/ + asset parameter part

Examples:

  • assets/asset/id/123 returns XML of asset ID „123“
  • assets/asset/id/123/version/1 returns XML of version 1 of asset ID 123
  • assets/asset/id/123/currversion/-2 returns XML of checked out version of asset ID 123
  • assets/asset;censhare:asset.id=123;censhare:asset.currversion=-2 returns XML of checked out version of asset ID 123
  • assets/asset;censhare:resource-key=transform:product returns XML of current version of first asset with resource key “transform:product”

Accessing files

Syntax: assets/ + storage parameter part + / file

Examples:

  • assets/asset/id/123/storage/master/file returns master file of asset ID 123 „
  • assets/asset/id/123/storage/preview/file returns preview file of asset ID „123“
  • assets/asset/id/123/element/actual/page/1/storage/preview/file returns preview of first page of asset ID 123
  • assets/asset/id/123/element/actual/0/storage/preview/file returns preview of element index 0 of asset ID 123
  • assets/asset;censhare:resource-key=transform:product/storage/master/file returns master file of first asset with resource key “transform:product”

Get asset icon metadata

Syntax: assets/ + icon parameter part

Examples:

  • assets/asset/id/123/icon returns asset icon of asset ID 123
  • assets/asset/id/123/version/1/icon returns asset icon of version 1 of asset ID 123
  • assets/asset/id/123/currversion/-2/icon returns asset icon of checked-out version of asset ID 123
  • assets/asset/id/123/icon/iconset/default returns asset icon of default iconset of asset ID 123
  • assets/asset/id/123/icon/iconset/default/background/dark returns asset icon of default iconset for dark background look&feel of asset ID 123

Get asset icon files

Syntax: assets/ + icon parameter part + /file

Examples:

  • assets/asset/id/123/icon/file returns asset icon of asset ID 123
  • assets/asset/id/123/version/1/icon/file returns asset icon of version 1 of asset ID 123
  • assets/asset/id/123/currversion/-2/icon/file returns asset icon of checked-out version of asset ID 123
  • assets/asset/id/123/icon/iconset/default/file returns asset icon of default iconset of asset ID 123
  • assets/asset/id/123/icon/iconset/default/background/dark/file returns asset icon of default iconset for dark background look&feel of asset ID 123

Transformations

Syntax: assets/ + ; + transformation parameter

Examples:

  • assets/asset/id/123/transform;key=test;format=xml returns result of transformation with key “test” and additional parameter “format” with value “xml”
  • assets/asset/id/123/transform;key=test;format=xml;param1=a;param2=b returns result of transformation with key „test“ and additional parameter. The result of the XML is returned. Following parameters are available in XSLT:

<param name="asset-id"/>“ <!-- contains value „123“  -->
<param name="key"/>       <!-- contains value „test“ -->
<param name="format"/>    <!-- contains value „xml“  -->
<param name="param1"/>    <!-- contains value „a“    -->
<param name="param2"/>    <!-- contains value „b“    -->

  • If you use an HTTP-post request, the payload is expected to be an XML text and then is available from the XSLT through:

<param name="data"/>“     <!-- contains post payload xml -->

  • To avoid specifying a “dummy” asset by ID for a transformation that actually doesn’t work on a specific asset, the transformation may be called on itself:

<http://localhost:9000/ws/rest/assets/asset;censhare:resource-key=rest_test/transform;key=rest_test;hello=foo;world=bar>

Zip files

Syntax: REST URL to ZIP file + ;container=zip

Examples:

  • assets/asset/id/123/storage/master/file;container=zip returns the list of files contained in the zip:

<entries>
  <entry name="test/"/>
  <entry name="test/test.pdf"/>
  <entry name="test1.jpg"/>
  <entry name="test/"/>
</entries>

  • assets/asset/id/123/storage/master/file;container=zip/docProps/thumbnail.jpeg returns file “thumbnail.jpeg” of folder “docProps” of master ZIP file of asset ID 123

Icons (not suitable for censhare 5 web client)

Syntax: resources/icon/ + icon parameter part + /file

Examples:

  • resources/icon/add/file returns icon with key “add”
  • resources/icon/add/iconset/default/file returns icon of default iconset with key “add”
  • resources/icon/add/iconset/default/background/dark/file returns icon of default iconset for dark look&feel with key “add”

Asset queries

Syntax: assets/all; + search parameter part Returns XML of any assets that matches with given search criteria. Default limit is 1000 assets.

Examples:

  • assets/all;censhare:asset.type=picture. returns every asset XML whose type is “picture”
  • assets/all;censhare:asset.type=picture.;censhare:text.meta=ipod returns every asset XML whose type is “picture” and meta data contains “ipod”
  • assets/all;censhare:asset.type=picture.;censhare:asset.name=ipod/transform;key=test returns a transformation with key „test“ of every asset XML whose type is “picture” and name contains “ipod”

For complex asset queries, HTTP post requests are used with a query expressed in XML as payload.

curl -X POST -T "asset-query.xml" -u rm: http://rm-serv:9000/ws/rest/service/assets/query“
 
-X -X/--request <command>
-T -T/--upload-file <file>
-u -u/--user <user:password>

Examples:

Query for assets with „my tasks“ and (asset type is picture or asset type is video)

<query count-rows="false" expand-limit="1000" full="200" limit="200" rel-limit="2147483647" start-full="0" start-row="0" type="asset" xmlns:corpus="http://www.censhare.com/xml/3.0.0/corpus">
    <condition name="censhare:function.my-tasks" op="=" value="1"/>
    <or>
        <condition expanded-nodes="picture." name="censhare:asset.type" op="=" partial-load-tree="true" value="picture.*"/>
        <condition expanded-nodes="video." name="censhare:asset.type" op="=" partial-load-tree="true" value="video.*"/>
    </or>
</query>

Accessing File systems

Note that for security reasons, external access is limited to the temporary file system.

Syntax: filesystem“ + URL to file

Examples:

  • filesystem/temp/1234456/10000.pdf returns file “10000.pdf” in folder “1234456” of temporary file system “temp”
  • filesystem/assets/13/89/138931.jpg returns file “138931.jpg” of the “assets” file system

Server statistics

Syntax:

server-statistics
server-statistics/key/+ [key of service]
server-statistics/key/+ [key of service] + /latest

Examples:

<server-statistics>
    <record timestamp="1385035030259" key="JVM" type="performance">
        <components>
            <component title="used memory" value="248.18369" min="242.9569" max="248.18369"/>
            <component title="total memory" value="764.5" min="764.5" max="764.5"/>
        </components>
    </record>
</server-statistics>

Additional resources