The Imixs-REST Service API

The representational state transfer (REST) is an architectural style, to present a service interface in a Web-based way. The API and core functionality of Imixs-Workflow is published by an open and platform independent RESTful Web service interface. The Imixs-Workflow REST services can be adopted easily by any kind of Internet client component.

Resources and URIs

An URI is a unique resource identifier which can be used to GET or PUT a unique resource through a RESTful service interface. The REST service interface of Imixs-Workflow publishes a set of resources which are representing WorkItems, Attachments, Reports and Model information. The different resources provided by Imixs-Workflow are divided in the following groups, where each group represents a different aspect of the Imixs-Workflow engine:

URI Resource Description
/workflow/ The Workflow resource provides resources and methods to get, create or modify workitems
/model/ The Model resource provides resources and methods to get, create or modify a workflow model
/report/ The Report resource provides resources and methods to create or execute a report based on a report definition
/entity/ The Entity resource provides resources and methods to query entities and control the index used by the EntityService EJB

Note: The root context of the REST Service is defined by the web application (web.xml) containing the REST Service. The default root context is “/rest-service/”.

The Representation of Business Objects

Each resource published by the Imixs-Workfow REST API is represented by common response and request object format. This format reflects a representation of the internal Business Object ItemCollection. Business objects can be represented in XML or JSON format.

XML Business Object

The following example shows a business object in XML representation used for request and response objects:

<entity xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <item>
       <name>$modelversion</name>
       <value xsi:type="xs:string">1.0.1</value>
    </item>
    <item>
       <name>$processid</name>
       <value xsi:type="xs:int">1000</value>
    </item>
    <item>
       <name>$activityid</name>
       <value xsi:type="xs:int">10</value>
    </item>
    <item>
       <name>_subject</name>
       <value xsi:type="xs:string"> Optionales Daten Feld</value>
    </item>
</entity>

JSON Business Object

The following example shows a business object in JSON representation used for request and response objects:

{"item":[
 {"name":"$modelversion","value":{"@type":"xs:string","$":"1.0.1"}},
 {"name":"$processid","value":{"@type":"xs:int","$":"1000"}}, 
 {"name":"$activityid","value":{"@type":"xs:int","$":"10"}}, 
 {"name":"_subject","value":{"@type":"xs:string","$":"Hello World"}}
]}

Depending on the Rest Service Implementation the JSON format for response object can deviate in the following simplified presentation style (e.g. RESTeasy ):

{"item": [
    {"name": "$modelversion", "value": ["1.0.1"] },
    {"name": "$processid", "value": [2000] },
    {"name": "$activityid", "value": [10] },
    {"name": "_subject", "value": ["Hello World"] }
 ]}

The Imixs-Workflow REST API accepts the following media types:

  • text/html
  • application/xml
  • application/json

The following sections gives an detailed description of all resource groups defined by the Imixs-Workflow REST Service API: