<access-service>/api/v1/organisations/{orgId}/collections

​

URL structure

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

​

Supported methods and overview

• POST - creates a new folder (i.e. collection) within an organisation (specified by orgId), which involves specifying the following properties on the resulting folder:
  • The folder’s location and name.
  • ( Optionally ) Collaborators (as well as their permission sets).

​

Detailed description

• View - grants the collaborator the individual View permission on any files subsequently contained within this new folder, which allows these files’:
  • content to be viewed from a SafeShare application’s content viewer, as well as their
  • read-only views to be downloaded (via the GET method on the <content-service>/api/v1/objects/{objectId}/view endpoint).
• Download - grants the collaborator the individual View permission (provided by the View permission set), as well as the following additional permissions on any files subsequently contained within this new folder ² :
  • Download the file’s actual content ³ (via the GET method on the <content-service>/api/v1/objects/{objectId}/contents endpoint).
  • Print the file’s content ³ from a SafeShare application’s content viewer.
• Upload - grants the collaborator the individual permissions provided by the Download permission set, as well as the following permissions to perform these additional actions within this new folder ² (in the owner’s storage space):
  • Initialize a new Incomplete file object within this folder ² (via the POST method on the <access-service>/api/v1/organisations/{orgGroupId}/objects endpoint), through the Upload File permission.
  • Upload this Incomplete file object’s data, which changes the file object’s state to Created (via the POST method on the <content-service>/api/v1/objects/{objectId}/contents endpoint), again through the Upload File permission.
  • Upload a new version of a file (and its actual content) within this folder (via the POST method on the <content-service>/api/v1/objects/{objectId}/versions endpoint), through the Upload File permission.
  • Create a new folder within this folder ² (via this endpoint’s parentId parameter), through the Create Folder permission.
• Modify - grants the collaborator the individual permissions provided by the Upload permission set, as well as the following permissions to perform these additional actions on this new folder itself (or any files/folders subsequently contained within this new folder) ² in the owner’s storage space:
  • Rename the item (via the PUT method on either the <access-service>/api/v1/objects/{objectId} or <access-service>/api/v1/collections/{collectionId} endpoints). The Rename permission also provides access to a file’s other versions, which includes the ability to perform any of the following actions:
    • Retrieve information about all existing versions of the file (via the GET method on the <access-service>/api/v1/objects/{itemId}/versions endpoint).
    • Download the read-only view of any version of the file (via the GET method on the <content-service>/api/v1/versions/{versionId}/view endpoint).
    • Download the actual content of any version of the file (via the GET method on the <content-service>/api/v1/versions/{versionId}/contents endpoint).
    • Set another version of the file to be active (via the PUT method on the <access-service>/api/v1/objects/{itemId}/versions/{versionId} endpoint).
    • Permanently delete a version of the file other than the active one (via the DELETE method on the <access-service>/api/v1/objects/{itemId}/versions/{versionId} endpoint).
  • Remove the file (including all of its versions) or folder (including all of its content) to the Recycle Bin, via the DELETE method on the <access-service>/api/v1/objects/{objectId} endpoint (through the Remove (File) permission) or <access-service>/api/v1/collections/{collectionId} endpoint (through the Remove (Folder) permission), respectively.
    Important: Be aware that a more restrictive permission set applied to any items contained within this child folder being deleted are ignored and as such, these items will also be removed to the Recycle Bin.
  • Move the item to a different folder within a common folder hierarchy (via the PUT method on either the <access-service>/api/v1/objects/{objectId} or this endpoint’s parentId parameter). A common folder hierarchy is a folder hierarchy that contains this new folder (including items subsequently contained within it), in which the same collaborator has also been added (with either the Modify or Manage permission set) to a higher level (i.e. a common) folder, such that this higher level folder forms the top of the folder’s hierarchy.
• Manage - grants the collaborator the individual permissions provided by the Modify permission set, as well as the following permissions to perform these additional actions on this new folder itself (or any files/folders subsequently contained within this new folder) ² in the owner’s storage space:
  • Share the item with other collaborators, for:
    • files, via the POST method on the <access-service>/api/v1/organisations/{orgGroupId}/objects endpoint or PUT method on the <access-service>/api/v1/objects/{objectId} endpoint, or
    • folders, via this endpoint’s collaborators parameter or the PUT method on the <access-service>/api/v1/collections/{collectionId} endpoint.

​

Supported roles and conditions

• Originator - when this user:
  • is a member of the organisation whose ID is specified by {orgId} in the request’s URL and
  • will create and initially own the resulting folder.
• Originator, Collaborator and Ad hoc - when the parentId parameter is specified for a folder (within the organisation specified by {orgId}) on which this user is a collaborator with the Create Folder permission.
  Note: Such a collaborator user cannot set this endpoint’s collaborators parameter, unless this user also has the Share permission on the folder represented by parentId.

​

Required headers

• Authorisation: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...
  where the Bearer token is the appropriate access token.
• Content-Type: application/json

​

Required parameters

• name - The name to apply to the folder (in storage).
• parentId - The ID of an existing folder (within the organisation specified by {orgId}) that will contain this new folder. Specifying a value of 0 results in the new folder being created at the logical root location in storage.
  Example (creating a collection at the root location in storage):
  {
    "name": "Scenery",
    "parentId": "0"
  }
  

​

Optional parameters

• collaborators ( For collaborator users, requires the Share permission on parentId ) - A parameter containing the following optional sub-element parameters that relate to the collaborators being applied to this folder:
  • list - An array of elements about each collaborator, where each element of this array contains the following optional sub-elements:
    • email - The email address of the person to add as a collaborator to the folder. (Although this sub-element is optional, omitting it serves no purpose.)
    • permissionSet - The permission set to apply to this collaborator. This is done by specifying the ID of the permission set as a sub-element parameter of this parameter:
      • id - The ID of the permission set to apply to this collaborator. This ID can be obtained by calling the <access-service>/api/v1/permissions/sets API endpoint.
      Note: If this sub-element is omitted, then the View permission set is automatically applied to this collaborator.
  Tip: It is worthwhile your client application storing these set of collaborators and their respective permission sets (e.g. in its own object) because any modifications to one or more collaborators on an existing folder requires all collaborators and their permission sets to be specified in the request to modify a folder.
  Example (creating a new folder within an existing folder, while adding new collaborators each with different sets of permissions to this new folder):
  {
    "name": "Large Files",
    "parentId": "876543210987654321"
    "collaborators": {
      "list": [
        {
          "email": "chris.collaborator@xy-company.com",
          "permissionSet": {
            "id": 5
          }
        },
        {
          "email": "olly.originator@xy-company.com",
          "permissionSet": {
            "id": 3
          }
        },
        {
          "email": "adhoc.user@another-xy-company.com"
        }
      ]
    }
  }
  
  Note: The permission set with an ID of 5 is Upload and with an ID of 3 is Modify. See <access-service>/api/v1/permissions/sets for more information about permission sets.

​

Returns

• id - The ID value of the created folder.
• name - The name of the folder, which was set when the folder was created (using this endpoint).
• createdAt - The date and time when the folder was created.
• modifiedAt - The date and time when the folder was last modified, which should be the same as (or close to) that of createdAt above.
• shared - A boolean value that indicates whether or not the folder has been shared with any collaborators.
• parentId - The ID of the folder that contains this new folder. A value of 0 indicates that this new folder is located at the default logical root storage location.
  Example (response from creating a new folder within an existing folder):
  {
      "id": "876543210191817161",
      "name": "Large Files",
      "createdAt": "2014-10-15T01:19:08.294Z",
      "modifiedAt": "2014-10-15T01:19:08.294Z",
      "shared": true,
      "parentId": "876543210987654321"
  }