<access-service>/api/v1/dashboard/organisations

URL structure

https://access-service.xy-company.com/api/v1/dashboard/organisations

Supported methods and overview

• GET - retrieves a summary of information about each organisation configured on the Cocoon Data Platform, consisting of the organisation's ID and name, the storage space allocated to the organisation and its current usage, and the number of Cocoon Data users in the organisation with the Originator and Collaborator roles.

Note: This method takes no parameters.

Detailed description

This API endpoint retrieves a summary of information about each organisation configured on the Cocoon Data Platform, consisting of the organisation's ID and name, the storage space allocated to the organisation (in mebibytes/MiB) and its current usage (in bytes), and the number of Cocoon Data users in the organisation with the Originator and Collaborator roles.

The information returned by this API endpoint is utilized on the SafeShare Administration dashboard.

Supported roles

This API endpoint supports the following Cocoon Data user roles (as described in the SafeShare Administrator's Guide):

• SafeShare administrator

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...

Optional parameters

The following optional parameters can be sent in the URL of the GET request:

• searchText - Any text substring used to filter for all items in the response, where this text substring must match that of the organisation's field specified in searchColumn below (or any of these fields). If this parameter is omitted, then no filtering is performed.
• searchColumn - The organisation's field upon which the text substring (specified in searchText above) is used for filtering items returned in the response. The fields available to this text searching include:
  • name - the organisation's name,
  • contactEmail - the email address of the organisation's contact person,
  • id - the organisation's ID and
  • all - any of these fields above.
  If this parameter is omitted, then no filtering is performed.
• limit - A value from 0 to any positive integer, representing the maximum number of items to be returned in the response from the Cocoon Data Platform, where an individual item is high-level information about an organisation. If this parameter is omitted, then its value is 0 by default, which imposes no limit on the number of items returned.
• offset - A value representing the count order of all retrievable items (i.e. organisation summary information) from the Cocoon Data Platform returned in the response. Calls to this API endpoint could amount to potentially unmanagable numbers of items being returned from the Cocoon Data Platform. Since the order of these items in the response could differ significantly, based on the values of the orderBy and sortBy parameters below, this offset parameter provides pagination for items returned in responses, allowing items to be retrieved from any count greater than 0 (i.e. the first item returned in a response). If this parameter is omitted, then its value is 0 by default.
• orderBy - An enumeration (enum) value representing the order in which items (organisation summary information) are returned in the response. This parameter orders items according to the value of the sortBy parameter specified below. Ordering items can be in either ascending alphanumeric order (by specifying the value ASC for this parameter) or descending order (by specifying the value DESC). If this parameter is omitted, then its value is DESC by default.
• sortBy - An enum value representing the field (i.e. member) of a retrieved item by which items (i.e. organisation summaries) returned in the response will be sorted. Valid field values for this parameter include:
  • name - the organisation's name,
  • contactEmail - the email address of the organisation's contact person and
  • id - the organisation's ID.
  These enum values can also be specified using uppercase characters. If this parameter is omitted, then its value is id by default - bearing in mind that file object IDs are generated in numerical order.
  Example (GET request - retrieving high-level information about all configured organisations on the Cocoon Data Platform whose contact person's email address contains the text substring 'administrator'):

  https://access-service.xy-company.com/api/v1/dashboard/organisations/?searchText=administrator&searchColumn=contactEmail

Note: Calling this method without any parameters retrieves a list of all organisations configured on the Cocoon Data Platform.

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:

• items - An array containing high-level information about each organisation configured on the Cocoon Data Platform. Each element of this array contains summary of information about one of these percentage bands and is represented as an object, containing the following members:
  • organisationId - The ID of the organisation.
  • organisationName - The name of the organisation.
  • amountTotalQuota - The amount of storage space (in MiB) currently allocated to the organisation.
  • amountUsedQuota - The amount of storage space (in bytes) currently consumed by Cocoon Data users (i.e. with the Originator role) in the organisation.
  • originatorsCount - The number of users in the organisation with the Originator role.
  • collaboratorsCount - The number of users in the organisation with the Collaborator role.
• count - The maximum number of items (i.e. organisations) that can be returned in the response.
  Note: If the searchText and searchColumn parameters were specified in the request, then this value represents the total number of items (above) returned in the response.
• offset - The value of the offset which had been used in the request to this endpoint.
  Example (response):

  {
      "items": [{
          "organisationId": "1",
          "organisationName": "Default",
          "amountTotalQuota": 0,
          "amountUsedQuota": 0,
          "originatorsCount": 0,
          "collaboratorsCount": 0
      }, {
          "organisationId": "749418071827214336",
          "organisationName": "XY Company",
          "amountTotalQuota": 4194304,
          "amountUsedQuota": 2369728,
          "originatorsCount": 1,
          "collaboratorsCount": 1
      }],
      "count": "2",
      "offset": "0"
  }