API Documentation
Toggle TOC panel
<access-service>/api/v1/organisations/{orgGroupId}/statistics/plans

URL structure

1 https://access-service.xy-company.com/api/v1/organisations/{orgGroupId}/statistics/plans

where {orgGroupId} is the ID of an organisation.

Supported methods and overview

  • GET - retrieves a summary of information about all plans within an organisation (specified by orgGroupId) and Cocoon Data users with the Originator role which have been assigned to each plan.

Detailed description

This API endpoint retrieves a summary of information about all plans within an organisation (specified by orgGroupId) and Cocoon Data users with the Originator role which have been assigned to each plan.

All current plans within an organisation (see <access-service>/api/v1/organisations/{orgGroupId}/plans for more information) are returned in the response to this API endpoint.

Supported roles and conditions

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

  • Organisation administrator - when this user is a member of the organisation whose ID is specified by {orgGroupId} in 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...

Optional parameters

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

  • 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 information about a plan in an organisation (specified by orgGroupId). 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 plan 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 plan 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 ASC by default.
  • sortBy - An enum value representing the field (i.e. member) of a retrieved item by which items (i.e. an organisation's plans) returned in the response will be sorted. Valid field values for this parameter include:
    • name - the plan's name,
    • description - the description of the plan's quota and
    • quota - the amount of the plan's quota.
    These enum values can also be specified using uppercase characters. If this parameter is omitted, then its value is name by default.
    Example (GET request - retrieving information about all configured plans in an organisation on the Cocoon Data Platform sorted alphabetically by name):
    1 https://access-service.xy-company.com/api/v1/organisations/749418071827214336/statistics/plans?sortBy=name&orderBy=ASC

Note:

  • Calling this method without any parameters retrieves a list of all plans configured for the organisation (specified by orgGroupId).
  • A bug currently exists, which prevents orderBy and sortBy from having any effect on the output. This bug will be addressed in a future Cocoon Data Platform version. Therefore, for the time being, these parameters can be omitted from requests to this endpoint.

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:

  • item - An array containing information about each existing plan configured for this organisation (specified by {orgGroupId} in the request's URL). Each element of this array contains information about one of these plans and is represented as an object, containing the following members:
    • id - The ID of the plan.
    • name - The name of the plan.
    • quota - The plan's quota (in mebibytes/MiB).
    • originatorsCount - The number of Cocoon Data users with the Originator role (in this organisation) who have been assigned this plan.
    • percentageOfAllOriginators - The percentage of all users with the Originator role (in this organisation) who have been assigned this plan.
    • unusedPlanQuotaOriginatorsCount - The number of users who have been assigned this plan but have not used any storage allocated by this plan's quota.
    • usedPlanQuotaOriginatorsCount - The number of users who have been assigned this plan and have used storage allocated by this plan's quota.
    • exceededPlanQuotaOriginatorsCount - The number of users who have been assigned this plan but have exceeded the plan's quota.
  • count - The maximum number of items (i.e. plans) that can be returned in the response.
  • offset - The value of the offset which had been used in the request to this endpoint.
    Example (response):
    {
    "items": [{
    "id": "756753535244587008",
    "name": "Temporary Staff Originators",
    "quota": "4096",
    "originatorsCount": 0,
    "percentageOfAllOriginators": 0.0,
    "unusedPlanQuotaOriginatorsCount": 0,
    "usedPlanQuotaOriginatorsCount": 0,
    "exceededPlanQuotaOriginatorsCount": 0
    }, {
    "id": "749419742544326656",
    "name": "Staff Originators",
    "quota": "10240",
    "originatorsCount": 1,
    "percentageOfAllOriginators": 100.0,
    "unusedPlanQuotaOriginatorsCount": 0,
    "usedPlanQuotaOriginatorsCount": 1,
    "exceededPlanQuotaOriginatorsCount": 0
    }],
    "count": "2",
    "offset": "0"
    }