Chapter 13. REST API

Representational State Transfer (REST) is a style of software architecture of distributed systems (applications). It allows for a highly abstract client-server communication: clients initiate requests to servers to a particular URL with parameters if needed and servers process the requests and return appropriate responses based on the requested URL. The requests and responses are built around the transfer of representations of resources. A resource can be any coherent and meaningful concept that may be addressed (such as a repository, a Process, a Rule, etc.).
Red Hat JBoss BPM Suite provides REST API for individual application components. The REST API implementations differ slightly:
  • Knowledge Store (Artifact Repository) REST API calls are calls to the static data (definitions) and are asynchronous, that is, they continue running after the call as a job. These calls return a job ID, which can be used after the REST API call was performed to request the job status and verify whether the job finished successfully. Parameters of these calls are provided in the form of JSON entities.
  • Deployment REST API calls are asynchronous or synchronous, depending on the operation performed. These calls perform actions on the deployments or retrieve information about one ore more deployments.
  • Runtime REST API calls are calls to the Execution Server and to the Process Execution Engine, Task Execution Engine, and Business Rule Engine. They are synchronous and return the requested data as JAXB objects.
All REST API calls to Red Hat JBoss BPM Suite use the following URL with the request body: http://SERVER_ADDRESS:PORT/business-central/rest/REQUEST_BODY

Note

Note that it is not possible to issue REST API calls over project resources, such as, rules files, work item definitions, process definition files, etc. are not supported. Perform operation over such files with Git and its REST API directly.
Report a bug

13.1. Knowledge Store REST API

REST API calls to Knowledge Store allow you to manage the Knowledge Store content and manipulate the static data in the repositories of the Knowledge Store.
The calls are asynchronous; that is, they continue their execution after the call was performed as a job. The job ID is returned by most of the Knowledge Store REST calls, and this is used to request the job status and verify whether the job finished successfully. Other operations return objects like repository lists and organizational units.
Parameters and results of these calls are provided in the form of JSON entities.
Report a bug

13.1.1. Job calls

Most Knowledge Store REST calls return a job ID after it is sent. This is necessary as the calls are asynchronous and you need to be able to reference the job to check its status as it goes through its lifecycle. During its lifecycle, a job can have the following statuses:
  • ACCEPTED: the job was accepted and is being processed.
  • BAD_REQUEST: the request was not accepted as it contained incorrect content.
  • RESOURCE_NOT_EXIST: the requested resource (path) does not exist.
  • DUPLICATE_RESOURCE: the resource already exists.
  • SERVER_ERROR: an error on the server occurred.
  • SUCCESS: the job finished successfully.
  • FAIL: the job failed.
  • APPROVED: the job was approved.
  • DENIED: the job was denied.
  • GONE: the job ID could not be found.
    A job can be GONE in the following cases:
    • The job was explicitly removed.
    • The job finished and has been deleted from the status cache (the job is removed from status cache after the cache has reached its maximum capacity).
    • The job never existed.
The following job calls are provided:
[GET]   /jobs/{jobID}
returns the job status - [GET]

Example 13.1. Response of the job call on a repository clone request

"{"status":"SUCCESS","jodId":"1377770574783-27","result":"Alias: testInstallAndDeployProject, Scheme: git, Uri: git://testInstallAndDeployProject","lastModified":1377770578194,"detailedResult":null}"
[DELETE]   /jobs/{jobID}
removes the job - [DELETE]
Report a bug

13.1.2. Repository calls

Repository calls are calls to the Knowledge Store that allow you to manage its Git repositories and their projects.
The following repositories calls are provided:
[GET]   /repositories
This returns a list of the repositories in the Knowledge Store as a JSON entity - [GET]

Example 13.2. Response of the repositories call

[{"name":"bpms-assets","description":"generic assets","userName":null,"password":null,"requestType":null,"gitURL":"git://bpms-assets"},{"name":"loanProject","description":"Loan processes and rules","userName":null,"password":null,"requestType":null,"gitURL":"git://loansProject"}]
[DELETE]   /repositories/{repositoryName}
This removes the repository from the Knowledge Store - [DELETE]
[POST]   /repositories/
This creates or clones the repository defined by the JSON entity - [POST]

Example 13.3. JSON entity with repository details of a repository to be cloned

{"name":"myClonedRepository", "description":"", "userName":"", "password":"", "requestType":"clone", "gitURL":"git://localhost/example-repository"}
[POST]   /repositories/{repositoryName}/projects/
This creates a project in the repository - [POST]

Example 13.4. Request body that defines the project to be created

"{"name":"myProject","description": "my project"}"
[DELETE]   /repositories/{repositoryName}/projects/
This deletes the project in the repository - [DELETE]

Example 13.5. Request body that defines the project to be deleted

"{"name":"myProject","description": "my project"}"
Report a bug

13.1.3. Organizational unit calls

Organizational unit calls are calls to the Knowledge Store that allow you to manage its organizational units.
The following organizationalUnits calls are provided:
[GET]   /organizationalunits/
This returns a list of all the organizational units - [GET].
[POST]   /organizationalunits/
This creates an organizational unit in the Knowledge Store - [POST]. The organizational unit is defined as a JSON entity. This consumes an OrganizationalUnit instance and returns a CreateOrganizationalUnitRequest instance.

Example 13.6. Organizational unit in JSON

{
  "name":"testgroup",
  "description":"",
  "owner":"tester",
  "repositories":["testGroupRepository"]
}
[POST]   /organizationalunits/{organizationalUnitName}/repositories/{repositoryName}
This adds the repository to the organizational unit - [POST]. It also returns a AddRepositoryToOrganizationalUnitRequest instance.

Note

Deleting an organizational unit is not supported via the REST API. The removal of an organizational unit is only possible through the Business Central.
Report a bug

13.1.4. Maven calls

Maven calls are calls to a Project in the Knowledge Store that allow you to compile and deploy the Project resources.
The following maven calls are provided below:
[POST]   /repositories/{repositoryName}/projects/{projectName}/maven/compile/
This compiles the project (equivalent to mvn compile) - [POST]. It consumes a BuildConfig instance, which must be supplied but is not needed for the operation and may be left blank. It also returns a CompileProjectRequest instance.
[POST]   /repositories/{repositoryName}/projects/{projectName}/maven/install/
This installs the project (equivalent to mvn install) - [POST]. It consumes a BuildConfig instance, which must be supplied but is not needed for the operation and may be left blank. It also returns a InstallProjectRequest instance.
[POST]   /repositories/{repositoryName}/projects/{projectName}/maven/test/
This compiles and runs the tests - [POST]. It consumes a BuildConfig instance and returns a TestProjectRequest instance.
[POST]   /repositories/{repositoryName}/projects/{projectName}/maven/deploy/
This deploys the project (equivalent to mvn deploy) - [POST]. It consumes a BuildConfig instance, which must be supplied but is not needed for the operation and may be left blank. It also returns a DeployProjectRequest instance.
Report a bug