API

Documents the REST API for the User Directory API app

Authentication

You should authenticate as a user with administrator credentials. To use Basic Authentication with the API, send the username and password associated with the account.

For example, if you’re accessing the API via cURL, the following command would authenticate you if you replace 'admin' with your username. cURL will prompt you to enter the password.

curl -u admin https://localhost:2990/jira/rest/nl-avisi-sync-add-on/1.0/directories

For simplicity sake, we will not repeat the authentication for the resources below.

List directories

GET https://localhost:2990/jira/rest/nl-avisi-sync-add-on/1.0/directories/

This endpoint lists all the directories that are available in the host product. Note that not all directories are syncable, for example the internal directory. This is indicated by the attribute synchronisable.

200 Directory list successfully retrieved.

[
  {
    "id": 1,
    "name": "JIRA Internal Directory",
    "type": "INTERNAL",
    "description": "JIRA default internal directory",
    "synchronisable": false
  }
]

Sync a directory

POST https://localhost:2990/jira/rest/nl-avisi-sync-add-on/1.0/directories/:id/actions/sync?blocking=false

Request a directory to start syncing immediately.

Path Parameters

Name	Type	Description
:id	integer	The identifier of the directory to sync

Query Parameters

Name	Type	Description
blocking	boolean	True if you want the call to be synchronous (that is: you want to wait for the synchronisation to finish). False if you want th e call to be asynchronous (that is: you want the sync to start, but not wait for it to finish.), your call will return immediately.

200

{
  "message": "synchronisation started in the background"
}

OR when blocking is true:

{
  "message": "synchronisation finish"
}

400 The directory is not syncable, this is for example the case for the internal directory.

{
  "message": "directory is not syncable"
}

409 The directory is currently syncing. The sync was either triggered by the schedule of the host product that syncs the user directories regularly. Another cause may be that the directory is sycing or still syncing as a result from earlier or another request via this API.

{
  "message": "directory is currently syncing"
}

Bitbucket Server doesn’t like synchronous calls. See BSERV-7073 and BSERV-7070.

List users in a specific directory

GET https://localhost:2990/jira/rest/nl-avisi-sync-add-on/1.0/directories/:id/users

Lists the users in a specific directory. A maximum of 100 users is returned. If there are more users, the response will contain a key named 'next', the value is a url that points to the next 'page' of results. A cursor value denotes the position in the list of users where the current call left off.

Path Parameters

Name	Type	Description
:id	integer	The identifier of the directory

Query Parameters

Name	Type	Description
limit	string	Limits the number of users returned to a number smaller than the default of 100.
cursor	integer	A cursor that defines the starting point in the user list. It is used for paging through the list of users. The cursor is retrieved from the response of the previous call to this endpoint.

200 A response showing a url to the next 'page' and the first page of users up to the cursor in the query parameter in the next url.

{
  "next": "http://localhost:2990/jira/rest/nl-avisi-sync-add-on/1.0/directories/10000/users?cursor=eyJzdGFydCI6Mn0%3D",
  "items": [
    {
      "name": "gerstree",
      "displayName": "Gert-Jan van de Streek"
    },
    {
      "name": "fatdemir",
      "displayName": "Fatih Demir"
    }
  ]
}