[Server] API Methods for OKR board

Change log here.



Before we start, check the auth guide.


Get all Workspaces

GET /rest/oboard/1.0/api/v1/workspaces returns all the workspaces for the OKR board.

Request

GET https://jirainstanceurl/rest/oboard/1.0/api/v1/workspaces

Example

GET https://jirainstanceurl/rest/oboard/1.0/api/v1/workspaces

No parameters

Response

[ { "id": 163, "iss": "aaaa-02cd-aaa-aaa-0c946df6b24b", "name": "GIANT", "key": "GG" }, { "id": 164, "iss": "aaaa-02cd-aaa-aaa-0c946df6b24b", "name": "WS for Tests", "key": "CR" } ]

 


Get List of Intervals for a Workspace

GET /rest/oboard/1.0/api/v1/intervals returns all intervals for a given workspace.

Request

Example

Field

Required

Description

Field

Required

Description

workspaceId

Yes

The if of workspace.

Response


Get List of Groups

GET /rest/oboard/1.0/api/v1/groups returns all groupIds for a given workspace.

Request

Example

Response

Field

Required

Description

Field

Required

Description

workspaceId

Yes

The ID of workspace.

includeServiceGroups

No

Use includeServiceGroups = true if you need to get an id for the “no group“ entity.

Response


Get List of Users from Workspace

GET /rest/oboard/1.0/api/v1/users returns all users for a given workspace.

Request

Example

Field

Required?

Description

Field

Required?

Description

workspaceId

Yes

The ID of workspace.

roleId

No

Id of the user role.

  • 1 – User

  • 2 – Team Leader

  • 3 – Workspace Administrator

groupid (will be ready soon)

No

Get users from a certain group.

Response


Objectives

Get a list of objectives DEPRECATED

Please use /rest/oboard/1.0/api/v1/elements below

GET /rest/oboard/1.0/api/v1/objectives returns all objectives for a given workspace.

Request

Example

 

Get a list of elements NEW

GET /rest/oboard/1.0/api/v1/elements returns all objectives for a given workspace.

Request

Example

Field

Required?

Description

Field

Required?

Description

workspaceId [array]

Yes

The ID of workspace.

⚠️Here and for other “array“ parameters you need to send 2 get-parameters in the request with the same name.
Example:

groupIds [array]

No

Array of a group ids.

userIds [array]

No

Array of a owner ids.

typeIds [array]

Yes

Type of the objective

levelIds [array]

Yes

The id of Objective level (e.g. Company-level) use /rest/oboard/1.0/api/v1/levels to get the id of level for a given WS

hasParent

No

Flag to check if an objective has a parent obj.

intervalId

No

ID of the Interval

minGrade

No

Filter objectives with a grade above this value.
⚠️Can be used with the maxGrade only

maxGrade

No

Filter objectives with up to %value% grade.

limit

No (default 50)

A number of objectives returned in the response.

startAt

No

Offset for the request. Default = 0.


Create an objective

POST /rest/oboard/1.0/api/v1/objectives – create an objective.

Request

Example

Field

Required

Description

Field

Required

Description

workspaceId

Yes

The ID of workspace.

intervalId

Yes

The ID of interval in the workspace.

groupId

Yes

Group to be assigned for this objective.

ownerId

No (yes if typeid=1)

User ID (in the plugin).
⚠️The parameter is required for “personal“ objectives.

typeId Jun 10, 2021 updated

Yes

Type of the objective to create 

levelId Jun 10, 2021 New

Yes

Type of the OKR
should be taken for the request

GET /rest/oboard/1.0/api/v1/levels

parentObjectiveId

No

Put here the id of the objective if you want to set a parent objective.

contribute

No

If OKR is contributing or not to parent objective (if exists).

description

No (up to 1024 symbols)

Description for the OKR

name

Yes (up to 512 symbols)

Title for the OKR

Response

Update Objective

PUT /rest/oboard/1.0/api/v1/objectives – update an objective.

If you want to delete non-required fields you need:
Put ““ for string values, and null for non-sting.
e.g. "description":"", "ownerId":null

Request

Example

Field

Required

Description

Field

Required

Description

objectiveId

Yes

Objective ID that has to be changed.

workspaceId

Yes

The ID of workspace.

⚠️The WS cannot be changed, it’s needed only for validation purposes.

groupId

No

Group to be assigned for this objective.

ownerId

No (yes if typeid=1)

User ID (in the plugin).
⚠️The parameter is required for “personal“ objectives.

typeId Jun 10, 2021 updated

Yes

Type of the objective to create 

levelId Jun 10, 2021 New

Yes

Type of the OKR
should be taken for the request

GET /rest/oboard/1.0/api/v1/levels

parentObjectiveId

No

Put here the id of the objective if you want to set a parent objective.

contribute

No

If OKR is contributing or not to parent objective (if exists).

description

No

Description for the OKR

name

Yes

The title of OKR

Interval ID (coming soon)

Yes

The ID of interval in the workspace.

Response

Remove Objective From Workspace

Delete /rest/oboard/1.0/api/v1/objectives – remove objective and all the nested items

Request

Example

Field

Required

Description

Field

Required

Description

objectiveId

Yes

Objective ID that has to be changed.

workspaceId

Yes

The ID of workspace.

removeNestedItems* coming soon

No

The flag if the nested items need to be removed.

Response


Get Nested Items for an Objective DEPRECATED

Get /rest/oboard/1.0/api/v1/objectives/children – returns only the nested items for the given objective

Please use /rest/oboard/1.0/api/v1/elements/nested

Request

Example

Get Nested Items for an item NEW

Get /rest/oboard/1.0/api/v2/elements/nested – returns only the nested items for the given objective

Request

Example

Field

Required?

Description

Field

Required?

Description

parentId

Yes

Id of the objective.

workspaceId

Yes

The ID of the workspace where the objective is located.

searchType=1

Yes

First-level nested items

searchType=2

Yes

Full structure


Key Results

Get a list of Key Results

GET /rest/oboard/1.0/api/v1/objectives returns all objectives for a given workspace.

Request

Example

Fields are the same as for getting objective (above).

Response


Update Key Result

PUT /rest/oboard/1.0/api/v1/key-results – update key result

Request

Example

Field

Required

Description

Field

Required

Description

keyResultId

Yes

The id of a key result to update

workspaceId

Yes

The ID of the workspace where the KR is located.

groupId

Yes

Assigned group

ownerId

Yes

Assignee

fieldTypeId

No

Type of the KR result.

currentValue

Yes

Current Value for the KR

⚠️Pls note the for a binary KR you should use either 0 or 1

originalValue

Yes

Starting value for the KR

⚠️Pls note the for a binary KR you should use 0

targetValue

Yes

Filter By Target Value

⚠️Pls note the for a binary KR you should use 1

name

Yes

Name of a KR

description

No

Description of a KR


Create Key Result

POST /rest/oboard/1.0/api/v1/key-results – update key result

Request

Example

Field

Required

Description

Field

Required

Description

keyResultId

Yes

The id of a key result to update

workspaceId

Yes

The ID of the workspace where the KR is located.

groupId

Yes

Assigned group

ownerId

Yes

Assignee

fieldTypeId

No

Type of the KR result.

originalValue

Yes

Starting value for the KR

⚠️Pls note the for a binary KR you should use 0

targetValue

Yes

Filter By Target Value

⚠️Pls note the for a binary KR you should use 1

name

Yes

Name of a KR

description

No

Description of a KR

Response


Remove Objective From Workspace

Delete /rest/oboard/1.0/api/v1/key-results – remove objective and all the nested items

Request

Example

Field

Required?

Description

Field

Required?

Description

keyResultId

Yes

The id of a key result to update

workspaceId

Yes

The ID of the workspace where the KR is located.

Response