1. Welcome
Welcome to the FlowWright REST API Guide. This guide describes how to configure and use FlowWright’s REST API.
What is a REST API?
REST API’s are web APIs hosted on a web server that can be accessed from any platform, the platform could be a tool, different technology, or even a completely different operating system. REST utilizes the HTTP protocol to make requests to the web server or the application server. REST calls send a request object, the server processes the call and returns a response object.
Until v9.7, FlowWright’s REST API’s were a call that didn’t have any state, where each call must be authenticated with the server. In v9.7, we have implemented RESTful calls where it maintains state, once authenticated, the rest of the calls can be called without authenticating.
1.1 Installation
The REST API is installed and configured automatically through the FlowWright installer. REST API is installed within the following directory:
C:\inetpub\wwwroot\cDevWorkflowRESTAPI
1.2 API Security
The REST API is secured using 2 authentication mechanisms until v9.7 the REST API was secured using “Basic” authentication. In v9.7, FlowWright has implemented OAuth authentication, which is much more secure and high performance. OAuth is a token-based authentication and widely used security mechanism today, especially with Web applications. Please refer to the FlowWright OAuth guide for information on how to use the REST API using OAuth tokens.
2. REST API
The next couple of sections will show you how to access the REST API using a couple of different methods.
2.1 Accessing using REST API Site
The REST API provides a website with documentation, here’s how to access this site. Navigate to the following URL:
http://localhost/cDevWorkflowRESTAPI
The site should render as follows:
To view the REST API, documentation, and test the API calls, click the “API” on the top menu.
The above diagram displays a list of classes provided by the REST API. Click on the “deEngineService” class to view its REST API calls.
As you can see from the list, each call is identified with its HTTP method, GET, DELETE or POST, and the description of the call. Click on the call “getBuildVersion” to expand and view its documentation.
This call is a very simple REST API call, there are no parameters sent through the call, its make the call returns the FlowWright build version.
Let’s click the button “Try it out!” to view the response from the call.
The above graphic displays the response but also the URL to call the REST API call. The request URL is displayed in the “Curl” format and just a simple URL format. Response received from the FlowWright server; it shows the value “v9.7” with a status code of 200 = OK.
As you can see the above call returned a response without requiring any authentication. Most REST API calls within the API are under security and will require authentication. But there are a few calls that are informational and do not require any authentication.
2.2 Calling a REST API call with authentication
Let’s test a REST API call that requires authentication. Navigate to the class called “deUser”.
Navigate to the REST API call “getUsers”:
The above call displays a list of users from FlowWright. There’s one optional parameter “userStatus”. Let’s call the method by clicking the “Try it out!” button. Since this method requires authentication, you will be presented with the browser’s authentication dialog:
If the authentication is successful, then the following response will be displayed:
Since the authentication was successful, the response returned shows the user list for the call. By default, this call returns all users, but using the “userStatus”, the call can return all, active or disabled users.
If authentication was not successful, then you will see the following response.
2.3 More complex REST API calls
Depending on functionality, some REST API calls are simple, and some are more complex. Complexity is based on input parameters and their data structure. Here’s the REST API call to create a Workflow Instance using a workflow definition.
The above call sends HTTP POST request to the server using the information provided. The “id” and “instanceName” parameters are required parameters that are sent with the request. Provide the id for the Workflow definition and a name for the new workflow instance. If the call is successful, the following response will be returned using the JSON format:
3. MultiTenant REST API
FlowWright API is also supported in MultiTenant environments. To configure the REST API for MultiTenant, navigate to the following path:
C:\inetpub\wwwroot\cDevWorkflowRESTAPI
Open the file “Web.config” using any text editor and locate the following entry:
Change the value from “false” to “true”. This will make the REST API act in Multitenant mode. Now you can start making REST API calls. REST API call URL is the same but with the tenant name in the front of the URL.