JBoss.org Community Documentation

- Prev
- Next

## Chapter 17. Workbench Integration

## 17.1. REST

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 every calls to allow 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.

When using Java code to interface with the REST API, the classes used in POST operations or otherwise returned by various operations can be found in the `(org.kie.workbench.services:)kie-wb-common-services` JAR. All of the classes mentioned below can be found in the `org.kie.workbench.common.services.shared.rest` package in that JAR.

### 17.1.1. Job calls

Every Knowledge Store REST call returns its job ID after it was 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

- `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

  Returns a `JobResult` instance

  Example 17.1. An example (formatted) response body to the get 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: If the job is not yet being processed, this will remove the job from the job queue. However, this will not cancel or stop an ongoing job

  Returns a `JobResult` instance

### 17.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`

  Gets information about the repositories in the Knowledge Store

  Returns a `Collection<Map<String, String>>` or `Collection<RepositoryRequest>` instance, depending on the JSON serialization library being used. The keys used in the `Map<String, String>` instance match the fields in the `RepositoryRequest` class

  Example 17.2. An example (formatted) response body to the get repositories call

      [
        {
          "name":"wb-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"
       }
      ]

[POST] `/repositories`

  Creates a new empty repository or a new repository cloned from an existing (git) repository

  Consumes a `RepositoryRequest` instance

  Returns a `CreateOrCloneRepositoryRequest` instance

  Example 17.3. An example (formatted) response body to the create repositories call

      {
        "name":"new-project-repo",
        "description":"repo for my new project",
        "userName":null,"password":null,
        "requestType":"new",
        "gitURL":null
      }

[DELETE] `/repositories/{repositoryName}`

  Removes the repository from the Knowledge Store

  Returns a `RemoveRepositoryRequest` instance

[POST] `/repositories/{repositoryName}/projects/`

  Creates a project in the repository

  Consumes an `Entity` instance

  Returns a `CreateProjectRequest` instance

  Example 17.4. An example (formatted) request body that defines the project to be created

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

### 17.1.3. Organizational unit calls

Organizational unit calls are calls to the Knowledge Store that allow you to manage its organizational units, so as to organize the connected Git repositories.

The following `organizationalUnits` calls are provided:

[POST] `/organizationalunits`

  Creates an organizational unit in the Knowledge Store

  Consumes an `OrganizationalUnit` instance

  Returns a `CreateOrganizationalUnitRequest` instance

  Example 17.5. An example (formatted) request body defining a new organizational unit to be created

      {
        "name":"testgroup",
        "description":"",
        "owner":"tester",
        "repositories":["testGroupRepository"]
      }

[POST] `/organizationalunits/{organizationalUnitName}/repositories/{repositoryName}`

  Adds the repository to the organizational unit

  Returns a `AddRepositoryToOrganizationalUnitRequest` instance

[DELETE] `/organizationalunits/{organizationalUnitName}/repositories/{repositoryName}`

  Removes the repository from the organizational unit

  Returns a `RemoveRepositoryFromOrganizationalUnitRequest` instance

### 17.1.4. Maven calls

Maven calls are calls to a Project in the Knowledge Store that allow you compile and deploy the Project resources.

The following `maven` calls are provided:

[POST] `/repositories/{repositoryName}/projects/{projectName}/maven/compile`

  Compiles the project (equivalent to `mvn compile`)

  Consumes a `BuildConfig` instance. While this must be supplied, it's not needed for the operation and may be left blank.

  Returns a `CompileProjectRequest` instance

[POST] `/repositories/{repositoryName}/projects/{projectName}/maven/install`

  Installs the project (equivalent to `mvn install`)

  Consumes a `BuildConfig` instance. While this must be supplied, it's not needed for the operation and may be left blank.

  Returns a `InstallProjectRequest` instance

[POST] `/repositories/{repositoryName}/projects/{projectName}/maven/test`

  Compiles the project runs a test as part of compilation

  Consumes a `BuildConfig` instance

  Returns a `TestProjectRequest` instance

[POST] `/repositories/{repositoryName}/projects/{projectName}/maven/deploy`

  Deploys the project (equivalent to `mvn deploy`)

  Consumes a `BuildConfig` instance. While this must be supplied, it's not needed for the operation and may be left blank.

  Returns a `DeployProjectRequest` instance

### 17.1.5. REST summary

The URL templates in the table below are relative the following URL:

- `http://server:port/business-central/rest`

Table 17.1. Knowledge Store REST calls

URL Template | Type | Description
--- | --- | ---
/jobs/{jobID} | GET | return the job status
/jobs/{jobID} | DELETE | remove the job
/organizationalunits | GET | return a list of organizational units
/organizationalunits | POST | create an organizational unit in the Knowledge Store described by the JSON `OrganizationalUnit` entity
/organizationalunits/{organizationalUnitName}/repositories/{repositoryName} | POST | add a repository to an organizational unit
/organizationalunits/{organizationalUnitName}/repositories/{repositoryName} | DELETE | remove a repository from an organizational unit
/repositories/ | POST | add the repository to the organizational unit described by the JSON `RepositoryReqest` entity
/repositories | GET | return the repositories in the Knowledge Store
/repositories/{repositoryName} | DELETE | remove the repository from the Knowledge Store
/repositories/ | POST | create or clone the repository defined by the JSON `RepositoryRequest` entity
/repositories/{repositoryName}/projects/ | POST | create the project defined by the JSON entity in the repository
/repositories/{repositoryName}/projects/{projectName}/maven/compile/ | POST | compile the project
/repositories/{repositoryName}/projects/{projectName}/maven/install | POST | install the project
/repositories/{repositoryName}/projects/{projectName}/maven/test/ | POST | compile the project and run tests as part of compilation
/repositories/{repositoryName}/projects/{projectName}/maven/deploy/ | POST | deploy the project

- PrevChapter 16. Authoring Assets
- Top of page
- Front page
- NextChapter 18. Workbench High Availability