Introduction

You can get some delegation data via REST.





Authentication and Authorization

All REST requests shown in this document require authentication.

Authentication is handled by the Jira instance that hosts the app. Basic Authentication and OAuth can be used. 

In cases where the user cannot be authenticated or authorized, one of these error responses is returned:


All endpoints will return the following responses on authentication and authorization-related errors.

Invalid Licence

HTTP 401


Unauthorized (401)

Encountered a "401 - Unauthorized" error while loading this page.

Unauthorized access

Go to Jira home

Invalid User

HTTP 401

When used user is not valid then JIRA server returns html page like that

Unauthorized (401)

Encountered a "401 - Unauthorized" error while loading this page.

Basic Authentication Failure - Reason : AUTHENTICATED_FAILED

Go to Jira home




Getting Delegation Data

Get Delegates

GET /rest/delegation/api/1.0/delegation/getDelegates

Returns a JSON that shows the delegates of the given delegator in the given category.

Request

The request takes all parameters as query parameters.

<jira_url>/rest/delegation/api/1.0/delegation/getDelegates?delegator=<delegator>&category=<category>&datetime=<datetime>

Parameters

Parameter

Description

Required

Value Samples

delegator

Jira username of the user whose delegates are to be queried.

To query delegations of other users, the authenticated user must have View All permission.

See DEL v1.4 - Permissions

Yesuser1
category

In which category the delegates will be searched.

The value can be either general or the name of one of the categories created from the Delegation Categories page.

See DEL v1.4 - Delegation Categories

Yes
  • general
  • my category
datetime

The date for which delegates are queried.

Valid format is yyyy-MM-dd HH:mm:ss.

The given date will be evaluated according to the timezone of the Jira server.

If no date is given, the current time of the Jira server will be used.


2021-08-27 16:30:00

Examples

https://192.168.0.1/rest/delegation/api/1.0/delegation/getDelegates?delegator=user1&category=general&datetime=2021-05-10 12:45:00
https://192.168.0.1/rest/delegation/api/1.0/delegation/getDelegates?delegator=user2&category=expense

Responses

Success

HTTP 200

Returns delegates of the delegator as JSON.

{
   "delegator":"user1",
   "asOf":"2021-08-27 05:45:36 +0000",
   "category":"Expense",
   "delegates":[
      "user2",
      "user3"
   ]
}

Invalid Parameter

HTTP 400

When one of the required parameters is missing or one of the supplied parameter values is invalid.

{
   "status":400,
   "message":"category is required.",
   "timestamp":1630043290559,
   "errors":{
      "category":"category is required."
   }
}

Missing Permission

HTTP 403

When the querying user does not have the necessary permissions.

{
   "status":403,
   "message":"You do not have permission to view delegations.",
   "timestamp":1630044510592
}
{
   "status":403,
   "message":"You do not have permission to query delegations of other users.",
   "timestamp":1630044510592
}

Not Found

HTTP 404

When one of the supplied parameter values is not found.

{
   "status":404,
   "message":"Category with name \"test\" could not be found.",
   "timestamp":1630043572503
}






Get Delegators

GET /rest/delegation/api/1.0/delegation/getDelegators

Returns a JSON showing delegators of the given delegate in the given category.

Request

The request takes all parameters as query parameters.

<jira_url>/rest/delegation/api/1.0/delegation/getDelegators?delegate=<delegate>&category=<category>&datetime=<datetime>

Parameters

Parameter

Description

Required

Value Samples

delegate

Username of the user whose delegators are to be queried.

To query delegations of other users, the authenticated user must have View All permission.

See DEL v1.4 - Permissions

Yesuser1
category

In which category the delegators will be searched.

The value can be either general or the name of one of the categories created from the Delegation Categories page.

See DEL v1.4 - Delegation Categories

Yes
  • general
  • my category
datetime

The date for which delegators are queried.

Valid format is yyyy-MM-dd HH:mm:ss.

The given date will be evaluated according to the timezone of the Jira server.

If no date is given, the current time of the Jira server will be used.


2021-08-27 16:30:00

Examples

https://192.168.0.1/rest/delegation/api/1.0/delegation/getDelegators?delegate=user1&category=general&datetime=2021-05-10 12:45:00
https://192.168.0.1/rest/delegation/api/1.0/delegation/getDelegators?delegate=user2&category=expense

Responses

Success

HTTP 200

Returns delegators of the delegate as JSON.

{
   "delegate":"user1",
   "asOf":"2021-08-27 05:45:36 +0000",
   "category":"Expense",
   "delegators":[
      "user2",
      "user3"
   ]
}

Invalid Parameter

HTTP 400

When one of the required parameters is missing or one of the supplied parameter values is invalid.

{
   "status":400,
   "message":"delegate is required.",
   "timestamp":1630043290559,
   "errors":{
      "delegate":"delegate is required."
   }
}

Missing Permission

HTTP 403

When the querying user does not have the necessary permissions.

{
   "status":403,
   "message":"You do not have permission to view delegations.",
   "timestamp":1630044510592
}
{
   "status":403,
   "message":"You do not have permission to query delegations of other users.",
   "timestamp":1630044510592
}

Not Found

HTTP 404

When one of the supplied parameter values is not found.

{
   "status":404,
   "message":"User with name \"myuser\" could not be found.",
   "timestamp":1630043572503
}



  • No labels