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: