Chapter 11. 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 and Red Hat JBoss BRMS provide 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.
    The following two API's are only available in Red Hat JBoss BPM Suite.
  • 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 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.

11.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. All POST and DELETE return details of the request as a well as a job id that can be used to request the job status and verify whether the job finished successfully. The GET operations return information about repositories, projects and organizational units.
Parameters and results of these calls are provided in the form of JSON entities.

11.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 11.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]

11.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 11.2. Response of the repositories call

[{"name":"brms-assets","description":"generic assets","userName":null,"password":null,"requestType":null,"gitURL":"git://brms-assets"},{"name":"loanProject","description":"Loan processes and rules","userName":null,"password":null,"requestType":null,"gitURL":"git://loansProject"}]
[GET]   /repositories/{repositoryName}
This returns information on a specific repository - [GET]
[DELETE]   /repositories/{repositoryName}
This deletes the repository - [DELETE]
[POST]   /repositories/
This creates or clones the repository defined by the JSON entity - [POST]

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

{"name":"myClonedRepository", "description":"", "userName":"", "password":"", "requestType":"clone", "gitURL":"git://localhost/example-repository"}
[GET]   /repositories/{repositoryName}/projects/
This returns a list of the projects in a specific repository as a JSON entity - [POST]

Example 11.4. JSON entity with details of existing projects

[ {
  "name" : "my-project-name",
  "description" : "Project to illustrate REST output",
  "groupId" : "com.acme",
  "version" : "1.0"
}, {
  "name" : "yet-another-project-name",
  "description" : "Yet Another Project to illustrate REST output",
  "groupId" : "com.acme",
  "version" : "2.2.1"
} ]
[POST]   /repositories/{repositoryName}/projects/
This creates a project in the repository - [POST]

Example 11.5. 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 11.6. Request body that defines the project to be deleted

"{"name":"myProject","description": "my project"}"

11.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].

Example 11.7. Organizational unit list in JSON

[ {
  "name" : "EmployeeWage",
  "description" : null,
  "owner" : "Employee",
  "defaultGroupId" : "org.bpms",
  "repositories" : [ "EmployeeRepo", "OtherRepo" ]
}, {
  "name" : "OrgUnitName",
  "description" : null,
  "owner" : "OrgUnitOwner",
  "defaultGroupId" : "org.group.id",
  "repositories" : [ "repository-name-1", "repository-name-2" ]
} ]
[GET]   /organizationalunits/{organizationalUnitName}
This returns a JSON entity with info about a specific organizational unit - [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 11.8. Organizational unit in JSON

{
  "name":"testgroup",
  "description":"",
  "owner":"tester",
  "repositories":["testGroupRepository"]
}
[POST]   /organizationalunits/{organizationalUnitName}
This updates the details of an existing organizational unit - [POST].
Both the name and owner fields in the consumed UpdateOrganizationalUnit instance can be left empty. Both the description field and the repository association can not be updated via this operation.

Example 11.9. Update organizational unit input in JSON

{
  "owner" : "NewOwner",
  "defaultGroupId" : "org.new.default.group.id"
}
[DELETE]   /organizationalunits/{organizationalUnitName}
This deletes an organizational unit - [GET].
[POST]   /organizationalunits/{organizationalUnitName}/repositories/{repositoryName}
This adds the repository to the organizational unit - [POST].
[DELETE]   /organizationalunits/{organizationalUnitName}/repositories/{repositoryName}
This removes a repository from the organizational unit - [POST].

11.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.