URL structure
1 https://access-service.xy-company.com/api/v1/items/delta
Supported methods and overview
Detailed description
This API endpoint retrieves lists of file objects and folders (i.e. items), upon which a specifiable range of consecutive changes/activities have been conducted by the Cocoon Data user (whose access token is submitted in the request to this endpoint).
This endpoint is useful for client applications (such as SafeShare for Windows) that need to scan for item changes between those recorded on the Cocoon Data Platform and those conducted locally on the client application's file system (for a given Cocoon Data user). This scanning process is required to allow the client application to selectively synchronize items with any changes between those in remote storage and those locally on the file system (e.g. inside SafeShare for Windows' SafeShare folders).
Using this endpoint, client applications can avoid the need to scan every item (accessible to a user) on the Cocoon Data Platform to identify such differences, by only retrieving items that have changed across a limited (time) range of consecutive item-based changes/activities.
Items returned by this endpoint are grouped according the types of activities conducted on them:
- added - items that have been created or shared,
- removed - items that have been:
- modified - items that have:
- been removed to (or restored from) the Recycle Bin,
- been moved to a different location,
- been renamed,
- had a collaborator's permission set changed,
- been disabled and re-enabled (for Organisation administrators only).
Notes:
- For a Cocoon Data user who is a member of multiple organisations, the response from this API endpoint reflects (and includes) changes to all items across all organisations the user is a member of.
- Changes are reflected/paginated in the response in chronological order.
Supported roles and conditions
This API endpoint supports requests utilizing Cocoon Data user accounts with the following roles (as described in the Organisation Administrator's Guide) and conditions:
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:
-
cursor - The ID of the chronologically next activity entry, retrieved in the response (below) from a request to this endpoint. This ID value relates to the activity entry continuing on from this response's last activity entry (reflected in the response), which in turn is based on the combination of the values for cursor and pageSize (below) that had been submitted in the request for this response. The combination of these cursor and pageSize parameters provides a mechanism for paginating the results. If this cursor parameter is omitted, then its value is
0 by default, which is the earliest item-based activity entry recorded for this Cocoon Data user (whose access token is submitted in the request to this endpoint).
-
pageSize - A value from
1 to 100, indicating the number of activities on items (i.e. activity entries) to be reflected in the response. If this parameter is omitted, then its value is 10 by default.
Note: Avoid confusing this value with the number of items returned in the response (below). Since the pageSize value refers to numbers of individual activities on items, whereas the response (below) returns individual items themselves (as their IDs), then multiple (chronologically close) activities conducted on a single item are likely to result in fewer items appearing in the response than the actual value specified for pageSize.
Example (request): 1 https://access-service.xy-company.com/api/v1/items/749866326952308736/history?pageSize=30
Returns
A JSON-formatted response containing the following members:
-
added - An array of individual items (across one or more organisations) upon which the Cocoon Data user (whose access token is submitted in the request to this endpoint) has performed any of the added activities described in the Detailed description section (above), after the activity entry reflected by the cursor value submitted in the request.
-
removed - An array of individual items (across one or more organisations) upon which this Cocoon Data user has performed any of the removed activities described in the Detailed description section (above), after the activity entry reflected by the cursor value submitted in the request.
-
modified - An array of individual items (across one or more organisations) upon which this Cocoon Data user has performed any of the modified activities described in the Detailed description section (above), after the activity entry reflected by the cursor value submitted in the request.
-
cursor - The ID of the activity entry following the last of this Cocoon Data user's activities (based on the cursor and pageSize values submitted in the request to this API endpoint), reflected in this response. This is the chronologically next activity entry (after the last one reflected in this response).
Example (response): {
"added": [752047795879604224, 749883721599217664, 752389961810243584, 754515061074448384, 751980834491527168, 753099535735386112, 753099536981094400, 749866326952308736, 752389806390308864, 753099532388331520],
"removed": [749428714470961152, 749866151802368000, 749425267889729536],
"modified": [],
"cursor": "754583406708674560"
}
