Retrieving information about items

The Cocoon Data API's interaction with specific files and folders relies heavily on submitting requests to the API using the ID values of these items.

If your application does not store these items' IDs, information about a specific subset of all items recorded on the Cocoon Data Platform (matching specific/memorable criteria and scoped within a specific organisation to which the items belong) can be retrieved as a list. Such criteria could be a 'search' substring that matches a property of the item, such as the name of the item or its owner's name, or an enum value defining the sharing/ownership status of the item.

From this manageable list of items retrieved from an organisation, the required items' IDs can be obtained.

This page describes how to use the Cocoon Data API to retrieve a list of information about:

• All immediate items of a common parent,
• All items filtered by text search (i.e. items whose name or owner's email address/first name/last name contains a specified string),
• All items based on ownership or sharing status (where 'sharing status' refers to items that a Cocoon Data user either has shared or is a collaborator on) and
• All ancestral collections of an item.

This page also describes how to sort, order and paginate any list of items retrieved using these procedures.

Notes:

• Before retrieving a list of files and folders, your application must have a valid access token obtained by authenticating and authorizing a Cocoon Data user to the Cocoon Data Platform, where this user is either:
  • the owner of these items (i.e. items which they have created - see Initializing a new 'Incomplete' file object and Creating a folder to manage items for more information) or
  • a collaborator on these items, which other users have shared with them - see Sharing items for more information.
  Also, for more information about authenticating and authorizing Cocoon Data users to the Cocoon Data Platform, see Initiating authentication and authorization on the Authentication and authorization page of this guide and the Configuring client applications page of the SafeShare Administrator's Guide.
• The Supported roles (and conditions) section of each API endpoint page (accessible from the relevant procedures throughout this Developer's Guide) contains details about the roles a Cocoon Data user requires and the conditions they must meet, for requests to these endpoints (which would include a valid access token representing the user's authenticated session) to succeed.

Retrieving info about all immediate items of a common parent

Information about immediate child items (i.e. both files and folders) of a common parent can be retrieved as a list from the Cocoon Data Platform. This common parent can be either a parent folder of these child items, or the logical root level.

To retrieve this list of information about all immediate child items of a common parent, make a GET method request to this API endpoint:

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

with the collectionId URL parameter whose value is either:

• the parent folder's ID (i.e. of the folder that contains these child items), or
• 0 to specify items located at the logical root level.

The value of {orgId} in the URL path of the request is the ID of the organisation from which the items will be retrieved.

If the request was successful, a JSON object is returned in the response containing an items member whose value is an array of elements, where each element contains information about one of the retrieved files or folders.

Retrieving info about all items filtered by text search

Information about all items whose name or owner's email address/first name/last name contains a specified string, irrespective of an item's location or ownership, can be retrieved as a list from the Cocoon Data Platform. (This is effectively a text search feature.)

To retrieve a list of information about all items whose name or owner's email address/first name/last name contains a specified string, make a GET method request to the following API endpoint:

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

with the searchText URL parameter whose value contains the specified string itself. Be aware that it is not possible to specify both the searchText and collectionId (above) URL parameters in the same request.

The value of {orgId} in the URL path of the request is the ID of the organisation from which the items will be retrieved.

If the request was successful, a JSON object is returned in the response containing an items member whose value is an array of elements, where each element contains information about one of the retrieved files or folders.

Retrieving info about items based on ownership or sharing status

For a given organisation, the Cocoon Data Platform can retrieve a list of information about all items at a given location which:

• belong to a Cocoon Data user (represented by an access token),
• this user is a collaborator on,
• this user has access to,

OR

information about every item which this user has shared.

To retrieve this list of information about items based on these criteria, make a GET method request to the following API endpoint:

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

and specify the view URL parameter with an enum value of:

• owned-by-me to retrieve all items owned by a given Cocoon Data user ^* ,
• shared-with-me to retrieve all items that other Cocoon Data users have shared with a given Cocoon Data user ^* ,
• sharing to retrieve all items that a given Cocoon Data user ^* has shared with other people, or
• all to retrieve all items that a given Cocoon Data user ^* can access.

Tip: The view URL parameter can be used in conjunction with both the collectionId and searchText parameters (above) for additional filtering.

^* In each case, this Cocoon Data user is determined by a valid access token (representing this user) passed in the header of the request.

The value of {orgId} in the URL path of the request is the ID of the organisation from which the items will be retrieved.

If the request was successful, a JSON object is returned in the response containing an items member whose value is an array of elements, where each element contains information about one of the retrieved files or folders.

Retrieving info about all ancestral collections of an item

To retrieve information about all ancestral folders (back to the logical root level) of an item, make a GET method request to the following API endpoint:

• <access-service>/api/v1/items/{itemId}/ancestry

The value of {itemId} in the URL path of the request is the ID of the file or folder from which all ancestral folders (through to the logical root level) will be retrieved in the response.

If the request was successful, a JSON object is returned in the response containing a single array of elements, where each element contains information about an ancestral folder (in hierarchical order from the logical root level).

Sorting, ordering and paginating the list of item info

The list of information about all retrieved items from a common parent, filtered by text search or based on ownership or sharing status can be sorted, ordered and paginated (when making a GET method request to the following API endpoint):

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

by specifying the following additional URL parameters:

• sortBy - The item's field by which the items in the list is ordered. Valid enum values for this parameter are:
  • NAME - the item's name (which is the default value if this parameter is omitted),
  • OWNER - the item's owner,
  • MODIFIED - the date when the item was last modified, or
  • CREATED - the date when the item was created.
• orderBy - The sortBy field is ordered by the value of this field. Valid enum values for this parameter are:
  • ASC - for ascending alphanumeric or chronological order (which is the default value if this parameter is omitted), or
  • DESC - for descending alphanumeric or chronological order.
• limit - The maximum number of items returned in the response. If this parameter is omitted, its value is 10 by default.
• offset - The count order of all retrievable items from the Cocoon Data Platform filtered using other URL parameters in the request. If this parameter is omitted, its value is 0 by default.

For more information about the limit and offset URL parameters for paginating items returned in the response, see Optional parameters (of <access-service>/api/v1/organisations/{orgId}/items).

If the request was successful, a JSON object is returned in the response containing an items member whose value is an array of elements, where each element contains information about one of the retrieved files or folders.