<access-service>/api/v1/organisations/{orgId}/labels/{labelId}/priority

URL structure

https://access-service.xy-company.com/api/v1/organisations/{orgId}/labels/{labelId}/priority

where {orgId} is the ID of an organisation and {labelId} is the ID of one of this organisation's classifications.

Supported methods and overview

• PUT - shifts the priority of a classification (specified by labelId in an organisation specified by orgId) either up or down.

Detailed description

This API endpoint shifts the priority of a classification (specified by labelId in an organisation specified by orgId) either up or down. A classification's ID can be obtained by calling the GET method of the <access-service>/api/v1/organisations/{orgId}/labels API endpoint, which retrieves a list of information for all classifications configured in an organisation (specified by orgId).

A priority is defined by a series of consecutive positive integer numbers called priority integer values. These values are used for sorting classifications from the highest priority (i.e. a priority integer value of 1) through to the lowest priority (i.e. the highest priority integer value, which equals the total number of all classifications defined in an organisation).

When a new classification is added to an organisation, it is automatically given the lowest priority (i.e. the highest priority integer number). When any classification (except for the classification with the lowest priority) is deleted, then the priority integer numbers of all other classifications with a lower priority (i.e. higher integer values) are automatically decreased by a value of 1.

When a classification's priority is shifted:

• up - then the priority integer values of this classification and its neighboring classification (i.e. with the next lowest priority integer value) switch their priority values.
• down - then the priority integer values of this classification and its neighboring classification (i.e. with the next highest priority integer value) switch their priority values.

Supported roles and conditions

This API endpoint supports requests utilizing Cocoon Data user accounts with the following roles (as described in the Organisation Administrator's Guide) and conditions:

• Organisation administrator - when this user is a member of the organisation specified by the {orgId} of the request's URL.

The Cocoon Data Platform's resources available to one of these Cocoon Data users (above) is determined by the access token submitted in the header of requests to this endpoint.

Required headers

The appropriate access token as the Bearer token:

• Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...

Required parameters

The following required parameters must be sent in the URL of the PUT request:

• direction - Specify up to shift up the priority of the classification (specified by {labelId} in the request's URL) in the organisation (specified by {orgId}), or specify down to shift the classification's priority down.
  Example (request):

  https://access-service.xy-company.com/api/v1/organisations/760756644367081472/labels/766862496543055872/priority?direction=up

Returns

If the request succeeded, then an HTTP response status 200 OK is returned.

For successful requests only, a JSON-formatted response containing the following members is also returned:

• id - The ID of the classification.
• name - The name of the classification.
• description - The description of the classification.
• priority - The new priority value, which is used for sorting classifications from highest (i.e. a priority integer value of 1) through to the lowest priority (i.e. the highest priority integer value, which equals the total number of all classifications defined in an organisation).
• applyI18n - .
  Example (response):

  {
      "id":"766862496543055872",
      "name":{
          "value":"Unclassified"
      },
      "description":{
          "value":"Used for content that does not have a classification level. People who are not members of staff (or without security clearance) may view such content."
      },
      "priority":"2",
      "applyI18n":false
  }