[Server] API Methods for OKR board
- 1 Get all Workspaces
- 2 Get List of Intervals for a Workspace
- 3 Get List of Groups
- 4 Get List of Users from Workspace
- 5 Objectives
- 6 Key Results
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 |
---|---|---|
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 |
---|---|---|
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 |
---|---|---|
workspaceId | Yes | The ID of workspace. |
roleId | No | Id of the user role.
|
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 |
---|---|---|
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. |
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. |
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 |
---|---|---|
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). |
typeId Jun 10, 2021 updated | Yes | Type of the objective to create |
levelId Jun 10, 2021 New | Yes | Type of the OKR 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 |
---|---|---|
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). |
typeId Jun 10, 2021 updated | Yes | Type of the objective to create |
levelId Jun 10, 2021 New | Yes | Type of the OKR 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 |
---|---|---|
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 |
---|---|---|
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 |
---|---|---|
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 |
---|---|---|
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 |
---|---|---|
keyResultId | Yes | The id of a key result to update |
workspaceId | Yes | The ID of the workspace where the KR is located. |