Red Hat Training

A Red Hat training course is available for Red Hat Decision Manager

Chapter 11. Knowledge Store REST API

REST API calls to the Knowledge Store REST API allow you to manage the organization units, repositories, and projects.

All POST and DELETE calls return details about the request as well as a job ID that can be used to request the job status and verify whether the job finished successfully. The GET calls return information about repositories, projects, and organizational units.

Parameters and results of these calls are provided in the form of JSON entities. Java classes for different entities are available in the org.guvnor.rest.client package and are referenced in the following text.

11.1. Job Calls

Most Knowledge Store REST calls return a job ID after they are issued. This is necessary as the calls are asynchronous and it is required to be able to reference the job later to check its status as it goes through a job lifecycle.

During its lifecycle, a job can have the following statuses:

Table 11.1. Job Statuses

StatusDescription

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 side 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 a status cache. A job is removed from a status cache after the cache has reached its maximum capacity.
  • The job never existed.

The following job calls are provided:

[GET] /jobs/JOB_ID

Returns a status of the given JOB_ID.

Example 11.1. Formatted Response to GET Job Call on Repository Clone Request

{
  "status" : "SUCCESS",
  "jobId" : "1377770574783-27",
  "result" : "Alias: testInstallAndDeployProject, Scheme: git, Uri: git://testInstallAndDeployProject",
  "lastModified" : 1377770578194,
  "detailedResult" : null
}
[DELETE] /jobs/JOB_ID
Removes a job with the given JOB_ID. If the job is not being processed yet, the call will remove the job from the job queue. However, this call will not cancel or stop an ongoing job.

Both of these job calls return a JobResult instance.

11.2. Organizational Unit Calls

Organizational unit calls are calls to the Knowledge Store that allow you to manage its organizational units which are useful to model departments and divisions. An organization unit can hold multiple repositories.

The following organizational unit calls are provided:

[GET] /organizationalunits/

Returns a list of all organizational units.

Example 11.2. Organizational Unit List in JSON Format

[ {
  "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/ORGANIZATIONAL_UNIT_NAME
Returns information about a specific organizational unit.
[POST] /organizationalunits/

Creates an organizational unit in the Knowledge Store. The organizational unit is defined as a JSON entity. The call requires an OrganizationalUnit instance and returns a CreateOrganizationalUnitRequest instance.

Example 11.3. Organizational Unit in JSON Format

{
  "name" : "testgroup",
  "description" : "",
  "owner" : "tester",
  "repositories" : ["testGroupRepository"]
}
[POST] /organizationalunits/ORGANIZATIONAL_UNIT_NAME

Updates the details of an existing organizational unit.

Both the name and owner fields in the required UpdateOrganizationalUnit instance can be left empty. Neither the description field nor the repository association can be updated using this operation.

Example 11.4. Update Organizational Unit Input in JSON Format

{
  "owner" : "NewOwner",
  "defaultGroupId" : "org.new.default.group.id"
}
[DELETE] /organizationalunits/ORGANIZATIONAL_UNIT_NAME
Removes a specified organizational unit.
[POST] /organizationalunits/ORGANIZATIONAL_UNIT_NAME/repositories/REPOSITORY_NAME
Adds a repository to an organizational unit.
[DELETE] /organizationalunits/ORGANIZATIONAL_UNIT_NAME/repositories/REPOSITORY_NAME
Removes a repository from an organizational unit.

11.3. Repository Calls

Repository calls are calls to the Knowledge Store that allow you to manage its Git repositories and their projects.

The following repository calls are provided:

[GET] /repositories

Returns a list of repositories in the Knowledge Store.

Example 11.5. Response of Repository Call

[
  {
    "name": "bpms-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/REPOSITORY_NAME
Returns information about a specific repository.
[DELETE] /repositories/REPOSITORY_NAME
Removes a repository.
[POST] /repositories/

Creates or clones a repository defined by a JSON entity.

Example 11.6. JSON Entity with Details about Repository to Be Cloned

{
  "name": "myClonedRepository",
  "organizationalUnitName": "example",
  "description": "",
  "userName": "",
  "password": "",
  "requestType": "clone",
  "gitURL": "git://localhost/example-repository"
}

Example 11.7. JSON Entity with Details about Repository to Be Created

{
  "name": "myCreatedRepository",
  "organizationalUnitName": "example",
  "description": "",
  "userName": "",
  "password": "",
  "requestType": "create",
  "gitURL": "git://localhost/example-repository"
}
Important

Make sure you always include the organizationalUnitName key-value pair in your query and that the specified organization unit exists before you create or clone the repository.

[GET] /repositories/REPOSITORY_NAME/projects/

Returns a list of projects in a specific repository as a JSON entity.

Example 11.8. JSON Entity with Details about Existing Projects

[ {
  "name" : "my-project-name",
  "description" : "A project to illustrate a REST output.",
  "groupId" : "com.acme",
  "version" : "1.0"
}, {
  "name" : "yet-another-project-name",
  "description" : "Yet another project to illustrate a REST output.",
  "groupId" : "com.acme",
  "version" : "2.2.1"
} ]
[POST] /repositories/REPOSITORY_NAME/projects/

Creates a project in a repository.

Example 11.9. Request Body That Defines Project to Be Created

{
  "name" : "NewProject",
  "description" : "Description of the new project.",
  "groupId" : "org.redhat.test",
  "version" : "1.0.0"
}
[DELETE] /repositories/REPOSITORY_NAME/projects/PROJECT_NAME
Removes a project in a repository.