The Imixs RestClient
The Imixs-RestClient is a helper class to establish connections to a Rest Service Endpoint. The client can be used for general HTTP communication and also for the Imxis-Rest API.
Core Methods
The RestClient provides the following GET and POST core methods:
Method | Description |
---|---|
get(url) | Gets the content of a GET request from a Rest Service URI Endpoint. I case of an error the method throws a RestAPIException. |
get(url) | Posts a String data object with a specific Content-Type to a Rest URI Endpoint. This method can be used to simulate different post scenarios. |
registerRequestFilter(RequestFilter) | adds a request filter |
Imixs Rest-API Data Methods
The following methods can be used to GET and POST Imxis Workflow Data
Method | Description |
---|---|
setServiceEndpoint(String) | builds the serviceEndpoint based on a given URI |
setEncoding(String) | defines the encoding used for post requests |
setRequestProperty(String, String) | Set a single header request property. |
post(String, String, String) | Posts a String data object with a specific Content-Type to a Rest Service UR Endpoint |
postCollection(url, DocumentCollection) | POST MEHTHOD for a document collection |
get(url) | Gets the content of a GET request from a Rest Service URI Endpoint. |
The following example shows how to post a workitem:
ItemCollection workitem = new ItemCollection().model(MODEL_VERSION).task(1000).event(10); workitem.replaceItemValue("_subject", "some data"); // create client org.imixs.workflow.services.rest.RestClient restCLient = new org.imixs.workflow.services.rest.RestClient(BASE_URL); // process workitem String resultData = restCLient.post(BASE_URL + "workflow/workitem", XMLDocumentAdapter.writeItemCollection(workitem), MediaType.APPLICATION_XML, MediaType.APPLICATION_XML); List<ItemCollection> result = XMLDataCollectionAdapter.readCollection(resultData.getBytes());
The next example shows how to request the tasklist of a user:
// create client org.imixs.workflow.services.rest.RestClient restCLient = new org.imixs.workflow.services.rest.RestClient(BASE_URL); String resultData = restCLient.get(BASE_URL + "workflow/tasklist/creator/admin"); List<ItemCollection> result = XMLDataCollectionAdapter.readCollection(resultData.getBytes());
RequestFilter & Authentication
The Imixs-RestClient supports also custom “RequestFilters”. A Requestfilter implements the interface org.imixs.workflow.services.rest.RequestFilter and can be used to handle a HTTP Request.
public class MyFilter implements RequestFilter { public void filter(HttpURLConnection connection) throws IOException { // your code goes here... } }
There a several Request filters available to be used for authentication:
- BasicAuthenticator - for a BASIC authentication
- FormAuthenticator - for a form based authentication with a JSESSION cookie
- JWTAuthenticator - for authentication based on JSON Web Tokens
The following example shows how to use a BASIC authentication filter:
RestClient restClient = new RestClient(); // create a default basic authenticator BasicAuthenticator basicAuth = new BasicAuthenticator("myuser","mypassword"); // register the authenticator restClient.registerRequestFilter(basicAuth); ...
The Imixs Melman Project
The Imixs Melman Project provides a more convenient component library to interact with the Imixs-Workflow Rest API. The project is agnostic from an Imixs-Workflow Implementation and can be used in a microservice architecture. The components are based on Java JAX-RS and JAX-B.