 |
API Documentation
|
|
API Documentation
|
where {objectId} is the ID of a file object/Secure Object.
GET - retrieves information about file object/Secure Object (specified by objectId) 1 .PUT - modifies the properties of a file object (specified by objectId). This involves the file's owner or a collaborator with sufficient permissions on the file 2 , performing any combination of the following:DELETE - removes a file object (specified by objectId) to its owner's Recycle Bin (known as 'recycling'), which changes the file object's state to Recycled. This can be performed by the file's owner or a collaborator with sufficient permissions on the file 2 . DELETE method on a file object whose state is Incomplete (see <access-service>/api/v1/organisations/{orgGroupId}/objects for more information), deletes this file object immediately (i.e. without the file object being removed to the Recycle Bin).Notes:
- Both the
GETandDELETEmethods take no parameters.- 1 The
GETmethod relates to the active version of the file object (specified byobjectId).
This API endpoint serves a number of purposes:
GET method requests:
objectId). A file object's ID can be obtained using one of the following API endpoints:PUT method requests:
objectId):GET method on the <content-service>/api/v1/objects/{objectId}/view endpoint).GET method on the <content-service>/api/v1/objects/{objectId}/contents endpoint).POST method on the <content-service>/api/v1/objects/{objectId}/versions endpoint), through the Upload File permission.GET method on the <access-service>/api/v1/objects/{itemId}/versions endpoint).GET method on the <content-service>/api/v1/versions/{versionId}/view endpoint).GET method on the <content-service>/api/v1/versions/{versionId}/contents endpoint).PUT method on the <access-service>/api/v1/objects/{itemId}/versions/{versionId} endpoint).DELETE method on the <access-service>/api/v1/objects/{itemId}/versions/{versionId} endpoint).DELETE method on this endpoint), through the Remove (File) permission.objectId), which changes its state to Created, by associating the SHA-512 value of the file's encrypted data (specified through this endpoint's sha512 parameter). (Be aware that this data must have been encrypted locally - i.e. not via server-side encryption by the Content Service). For more information about initializing an Incomplete file object, see <access-service>/api/v1/organisations/{orgGroupId}/objects. 2 This owner or collaborator is a Cocoon Data user, whose access token is submitted in the request to this endpoint. A file object's:
3 Relates to the active version of the file.
DELETE method requests:
objectId) to its owner's Recycle Bin (known as 'recycling'), which changes the file object's state to Recycled.This API endpoint supports requests utilizing Cocoon Data user accounts with the following roles (as described in the Organisation Administrator's Guide) and conditions:
GET, PUT and DELETE methods, when this user owns the file object whose ID is specified by {objectId} in the request's URL.GET and PUT methods, when this user is a collaborator on the file object whose ID is specified by {objectId} in the request's URL. For the PUT method, such a collaborator user can set the:DELETE method, when this user is a collaborator with the Remove (File) permission on the file object whose ID is specified by {objectId} in the URL.The Cocoon Data Platform's resources available to a Cocoon Data user meeting the criteria above is determined by the access token submitted in the header of requests to this endpoint.
The appropriate access token as the Bearer token:
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...The following header is required if the body of the request has a JSON object:
Content-Type: application/jsonThe following optional parameters can be sent in the body of the PUT request, each as individual members of a JSON object:
objectId ) - A parameter containing the following optional sub-element parameters that relate to the collaborators being applied to this file object: objectId ) - The size (in bytes) of the file object's data (in its unencrypted form) to be recorded by the Cocoon Data Platform's Access Service. Specify this value to record the size of a completed file object's unencrypted data, which is to be encrypted locally by your client application. objectId ) - The ID of the classification to apply to (or modify on) the file object. If this parameter's value is an empty string or the parameter is omitted altogether, then no classification is applied to the file object and therefore, no classification restrictions (i.e. checks on Cocoon Data users' group membership and the association of these groups with classifications - see User group endpoints for more information) are placed on any collaborators added to this file object. objectId ) - The MIME type of the data associated with the file object. For example, if the data to be encrypted into this file object is an image in JPEG format, its MIME type value would be image/jpeg. objectId ) - The name to apply to the file object. For example, any new name for the file and its extension. objectId ) - The ID of the folder that will contain the file object (i.e. the folder to which the file object will be moved). Specifying a value of 0 results in the file being located at/moved to the default logical root storage location. objectId and the same collaborator's user account that initialized this file object ) - The SHA-512 value of the file object's encrypted data. objectId ) - The date and time from which collaborators can begin accessing the file object's content. Omitting this member makes the file object's content available immediately. When specifying this parameter, ensure its value complies with ISO8601 date/time format notation - i.e. "YYYY-MM-DDTHH:MM:SS.SSSZ". objectId ) - The date and time from which collaborators' access to the file object's content ceases. Omitting this member makes the file object's content available indefinitely (after its shareStartTime). As with shareStartTime, when specifying this parameter, ensure its value complies with ISO8601 date/time format notation - i.e. "YYYY-MM-DDTHH:MM:SS.SSSZ". If the request succeeded, then an HTTP response status 200 OK is returned.
For successful GET and PUT requests only, a JSON-formatted response containing the following members is also returned:
null. null. false. POST method request to this endpoint). This value is null if the name was never specified. null. server.useraccounttype. This I18N code could include the substring local, ldap or external. true after it sets the value of canGenerateView (below) to true and the Content Service has successfully generated and stored a read-only view of the file object's data. true after the file object's data has been successfully uploaded and stored and the size of this data is less than the maximum configured file size for generating a view (i.e. 20 MB by default). true) or not (false) two-factor authentication has been enforced for all members of the organisation. POST method request to this endpoint). This value is null if the mimeType was never specified. null. 0 indicates that this file object is located at the logical root location. incomplete for an initialized file object, created for a completed file or deleted for a deleted file. POST method on the <access-service>/api/v1/organisations/{orgGroupId}/objects endpoint), this date and time should match (or be close to) that of the createdAt value below. Otherwise, if the file object has since been modified (e.g. via a PUT method request to this endpoint), this date and time should reflect when the file object was last modified. null, then no classification was specified (i.e. the labelId parameter was specified with an empty string or this parameter was omitted) when the file object was initialized or created, or last updated. This means that no classification restrictions (i.e. checks on Cocoon Data users' group membership and the association of these groups with individual classifications - see User group endpoints for more information) have been placed on collaborators added to this file object. 0 indicates that this file object is located at the logical root location. object, which in turn indicates that information about item returned from this request is about a file object. null, then no classification was specified (i.e. the labelId parameter was specified with an empty string or this parameter was omitted) when the file object was initialized or created, or last updated (via a POST method request to this endpoint). null or 0. A value of null indicates that the file object's location in its hierarchy of folders (e.g. as indicated in a SafeShare application's list of items) are equivalent between this collaborator and the current owner of this file object. A value of 0 indicates that the file object is being shared from the logical root file area/location of this collaborator's account. In SafeShare applications, this occurs when the owner of this file object has shared the file object with this collaborator, but the file object's parent folder has not also been shared with this collaborator. null. 