<access-service>/api/v1/collections/{collectionId}/collections

​

URL structure

https://access-service.xy-company.com/api/v1/collections/{collectionId}/collections

​

Supported methods and overview

• GET - retrieves a list of information associated with all immediate child folders/collections contained within the folder specified by collectionId.

​

Detailed description

• Folders retrieved in the response are those to which a given Cocoon Data user (whose access token is submitted in the request to this endpoint) can access - i.e. as the owner of (or a collaborator on) the folder specified by collectionId. If this user is a collaborator on this folder, then only folders which this user is also a collaborator on are returned in the response.
• Any folders contained within these immediate child folders are excluded in the response.
  Tip: To retrieve information about any folder nested within these child folders, make a subsequent request to this endpoint with the collectionId value being the ID of the relevant nested folder.

• Are present at the root level of a specific organisation.
• The Cocoon Data user (whose access token is submitted in the request) has permission to move an item (specified through the movingItemId parameter below).
• The user (whose access token is submitted in the request) has permission to restore an item from the Recycle Bin (specified through the itemToRestoreId parameter below).

​

Supported roles and conditions

• Originator - when this user owns the folder whose ID is specified by {collectionId} in the request’s URL.
• Originator, Collaborator and Ad hoc - when this user is a collaborator on the folder whose ID is specified by {collectionId} in the URL.

​

Required headers

• Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...

​

Optional parameters

• organisationId ( Only applicable when the collectionId value is 0, which represents the root level location. ) - The ID of the organisation from which items (i.e. folders at the root level location) will be retrieved.
• movingItemId - The ID of an item (i.e. a file or folder) to restore to the folder/location (specified by collectionId). Specifying this parameter filters the response to folders which the Cocoon Data user (whose access token is submitted in the request) has permission to move this item.
  Note: This parameter cannot be specified in conjunction with itemToRestoreId. Doing so will cause the request to fail.
• itemToRestoreId - The ID of an item currently located in the Recycle Bin to restore to the folder/location (specified by collectionId). Specifying this parameter filters the response to folders which the Cocoon Data user (whose access token is submitted in the request) has permission to restore this item.
  Note: This parameter cannot be specified in conjunction with movingItemId. Doing so will cause the request to fail.
• limit - An integer value from 0 to 100, representing the maximum number of items (i.e. folders) to be returned in the response from the Cocoon Data Platform, where an individual item is information about a folder. A value of 0 imposes no limit on the number of items returned. If this parameter is omitted, then its value is 10 by default.
• offset - A value representing the count order of all retrievable items (i.e. folders) from the Cocoon Data Platform returned in the response. Since responses from this endpoint could amount to potentially unmanageable numbers of items being returned from the Cocoon Data Platform, 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 - ASC or DESC (default is ASC).
• view - Specify one of the following string values, which filters/retrieves only folders in the response according to the Cocoon Data user whose access token is submitted in the request to this endpoint:
  • owned-by-me - retrieves only folders that this user currently owns.
  • shared-with-me - retrieves only folders that this user is a collaborator on (i.e. other people have shared these folders with this user).
  • sharing - retrieves only folders that this user has shared with other people.
  • all - retrieves all items that this user has access to.

​

Returns

• id - The value of collectionId of the folder/location in the URL of this request.
• parentId - The ID of the folder/collection that contains the folder specified by collectionId. A value of 0 indicates that this folder (specified by collectionId) is located at the logical root location.
• name - The name of the folder specified by collectionId.
• createdAt - The date and time when this folder was created.
• modifiedAt - The date and time when this folder was last modified. When a folder is created (via the POST method on the <access-service>/api/v1/organisations/{orgId}/collections endpoint), this date and time should match (or be close to) that of the createdAt value below. Otherwise, if the folder has since been modified (e.g. via a PUT method request to this endpoint), this date and time should reflect when the folder was last modified.
• shared - A boolean value that indicates whether or not the folder has been shared with any collaborators.
  Note: If the request was made using the access token of an authenticated collaborator user (without the View Other permission) on the file object, then the value returned will be false.
• originator - A member containing information about the Cocoon Data user whose account was used to create this folder. This member contains the equivalent email and id sub-members only of either the owner member (above) or a collaborators array element (below). If these sub-members originally match those of the folder’s initial owner member and then the folder’s ownership changes to that of another Cocoon Data user, the owner member’s email and id values will change while the equivalent sub-member values of this originator member will remain unchanged.
• owner - A member containing information about the Cocoon Data user who is the current owner of the folder. This member contains the following sub-members:
  • id - The ID of this Cocoon Data user’s account.
  • email - The email address of the Cocoon Data user who owns this folder.
  • firstName - The first name set by this Cocoon Data user.
  • lastName - The last name set by this Cocoon Data user.
• permissions - An array listing the individual permissions that the owner above or a collaborator on (whose access token was used in the request to this endpoint), has inherited from the location represented by parentId.
• organisationId - The ID of the organisation that contains this folder.
• count - The total number of items (i.e. collections) below, returned in the response.
• offset - The value of the offset which had been used in the request to this endpoint.
• items - An array containing information about the folders (which are immediate children of collectionId), returned in the response to this endpoint. Each element of this array contains information about one of these folders, represented as an object containing all of the members above (except originator, count, offset and items) as well as the following members.
  • parentName - The name of the parent folder. Currently, this value is always null.
  • type - Should be collection, indicating that the type of item returned is a folder.
  • organisation - A member containing information about the organisation that contains this folder. This member contains the following sub-members:
    • name - The name of the organisation.
    • description - The organisation’s description (if this has been set).
    • id - The ID of the organisation.
  Example (response):
  {
      "id": "751980834491527168",
      "parentId": "0",
      "name": "Large Files",
      "createdAt": "2016-09-06T01:43:22.071Z",
      "modifiedAt": "2016-09-07T04:49:05.719Z",
      "shared": true,
      "originator": {
          "id": "749419842687528960",
          "email": "alex.originator@xy-company.com"
      },
      "owner": {
          "id": "749419842687528960",
          "email": "alex.originator@xy-company.com",
          "firstName": "Alex",
          "lastName": "Originator"
      },
      "permissions": [{
          "id": "66",
          "nameI18nCode": "server.permission.name.file.delete"
      }, {
          "id": "67",
          "nameI18nCode": "server.permission.name.folder.delete"
      }, {
          "id": "62",
          "nameI18nCode": "server.permission.name.download"
      }, {
          "id": "69",
          "nameI18nCode": "server.permission.name.move"
      }, {
          "id": "60",
          "nameI18nCode": "server.permission.name.view"
      }, {
          "id": "72",
          "nameI18nCode": "server.permission.name.delete.other"
      }, {
          "id": "63",
          "nameI18nCode": "server.permission.name.copy"
      }, {
          "id": "61",
          "nameI18nCode": "server.permission.name.print"
      }, {
          "id": "73",
          "nameI18nCode": "server.permission.name.share"
      }, {
          "id": "68",
          "nameI18nCode": "server.permission.name.rename"
      }, {
          "id": "71",
          "nameI18nCode": "server.permission.name.view.other"
      }, {
          "id": "65",
          "nameI18nCode": "server.permission.name.folder.create"
      }, {
          "id": "64",
          "nameI18nCode": "server.permission.name.file.upload"
      }],
      "organisationId": "749418071827214336",
      "count": "2",
      "offset": "0",
      "items": [{
          "id": "752389961810243584",
          "name": "Another",
          "parentId": "751980834491527168",
          "parentName": null,
          "createdAt": "2016-09-07T04:49:05.625Z",
          "modifiedAt": "2016-09-07T04:49:05.841Z",
          "type": "collection",
          "shared": true,
          "owner": {
              "id": "749419842687528960",
              "email": "alex.originator@xy-company.com",
              "firstName": "Alex",
              "lastName": "Originator"
          },
          "permissions": [{
              "id": "66",
              "nameI18nCode": "server.permission.name.file.delete"
          }, {
              "id": "67",
              "nameI18nCode": "server.permission.name.folder.delete"
          }, {
              "id": "62",
              "nameI18nCode": "server.permission.name.download"
          }, {
              "id": "69",
              "nameI18nCode": "server.permission.name.move"
          }, {
              "id": "60",
              "nameI18nCode": "server.permission.name.view"
          }, {
              "id": "72",
              "nameI18nCode": "server.permission.name.delete.other"
          }, {
              "id": "63",
              "nameI18nCode": "server.permission.name.copy"
          }, {
              "id": "61",
              "nameI18nCode": "server.permission.name.print"
          }, {
              "id": "73",
              "nameI18nCode": "server.permission.name.share"
          }, {
              "id": "68",
              "nameI18nCode": "server.permission.name.rename"
          }, {
              "id": "71",
              "nameI18nCode": "server.permission.name.view.other"
          }, {
              "id": "65",
              "nameI18nCode": "server.permission.name.folder.create"
          }, {
              "id": "64",
              "nameI18nCode": "server.permission.name.file.upload"
          }],
          "organisation": {
              "name": "XY Company",
              "description": "",
              "id": "749418071827214336"
          }
      }, {
          "id": "752389806390308864",
          "name": "Secret",
          "parentId": "751980834491527168",
          "parentName": null,
          "createdAt": "2016-09-07T04:48:28.570Z",
          "modifiedAt": "2016-09-07T04:48:28.656Z",
          "type": "collection",
          "shared": true,
          "owner": {
              "id": "749419842687528960",
              "email": "alex.originator@xy-company.com",
              "firstName": "Alex",
              "lastName": "Originator"
          },
          "permissions": [{
              "id": "66",
              "nameI18nCode": "server.permission.name.file.delete"
          }, {
              "id": "67",
              "nameI18nCode": "server.permission.name.folder.delete"
          }, {
              "id": "62",
              "nameI18nCode": "server.permission.name.download"
          }, {
              "id": "69",
              "nameI18nCode": "server.permission.name.move"
          }, {
              "id": "60",
              "nameI18nCode": "server.permission.name.view"
          }, {
              "id": "72",
              "nameI18nCode": "server.permission.name.delete.other"
          }, {
              "id": "63",
              "nameI18nCode": "server.permission.name.copy"
          }, {
              "id": "61",
              "nameI18nCode": "server.permission.name.print"
          }, {
              "id": "73",
              "nameI18nCode": "server.permission.name.share"
          }, {
              "id": "68",
              "nameI18nCode": "server.permission.name.rename"
          }, {
              "id": "71",
              "nameI18nCode": "server.permission.name.view.other"
          }, {
              "id": "65",
              "nameI18nCode": "server.permission.name.folder.create"
          }, {
              "id": "64",
              "nameI18nCode": "server.permission.name.file.upload"
          }],
          "organisation": {
              "name": "XY Company",
              "description": "",
              "id": "749418071827214336"
          }
      }]
  }