Third Light Developer Exchange

superbig

New User

Registered: 2020-11-18

Posts: 1

Listing all spaces, folders and files

Hi, how do would I go about doing the following:

1) List all spaces a API key has access to
2) List all folders within a space
3) List all files within these folders

Here I have made the assumption that creating a site- or space-specific API key has access to all spaces and/or the folders/files within said spaces

One of the confusing aspects is that you don't explain anywhere properly as far as I can tell what the difference between groups, contexts, folders, sections etc. is.

dominic

Third Light Staff

Registered: 2013-06-06

Posts: 116

Re: Listing all spaces, folders and files

Hi,

Spaces are in a hierarchy, so you can't get all accessible spaces in a single call. The place to start is to call /rest/v1/contexts/dom0/children. This will return a list of spaces equivalent to what a user would see when clicking the top, Site, link in the Spaces toolbar.
Where there are sub-spaces, you can call the same again in turn.

For each space, one of the returned pieces of information is: backingFolderId - this is an ID that can be used in Folder API calls.

Folders are similar, in that you recurse down the tree. /rest/v1/folders/{folderId}/folders returns the sub-folders for a given folder. To get the top-level folders in a space, call this with the backingFolderId from before.

You can get details for multiple folder IDs in one go, using /rest/v1/folders/multi, or individually at /rest/v1/folders/{folderId}

For files, you can get the list of files within a single folder from /rest/v1/folders/{folderId}/files

File details can be retrieved similarly to folder details, but from the /rest/v1/files/multi and /rest/v1/files/{fileId} endpoints.

A Space API key has access to all content within that space. It may have access to other spaces if the space itself is a member (as opposed to just having users in common).

A Space has three key components:
- Location (via its Context)
- Membership (via its Group)
- Storage (via its Folder)

Contexts represent navigation. As above, all Spaces have a context, but there are also non-space contexts - e.g. `dom0`, which represents the whole site, but has neither associated Membership nor Storage.

Groups represent membership and settings. As above, all Spaces have a group, but some groups (e.g. those created by External Authentication integrations, or the special "Everyone" and "Site Admins" tokens) do not have a corresponding Space.

Folders contain content. Each space has a Folder which represents the top-level view of that space. Other folders have a parent folder.

mtaylor

Member

Registered: 2021-04-26

Posts: 4

Re: Listing all spaces, folders and files

Hi, we are calling /rest/v1/contexts/dom0/children to list top-level spaces, using a site-level API key.

We have 8 top-level spaces (including the Admins space), however the call only shows 6 of those (not our most recently created ones).

I assumed that site level keys as opposed to user level keys have full visibility. For clarity, we are testing in version 3.3 of Chorus.

How do we configure which spaces get returned by the API and how do we give the global API key permission to be able to do so?

dominic

Third Light Staff

Registered: 2013-06-06

Posts: 116

Re: Listing all spaces, folders and files

Hi,

The main feature of a site-level API key is the ability to create sessions for other users (commonly, to implement an authentication integration, such as that supported by the Drupal module) - however all other actions are still performed on behalf of a specific user. You can find out which account by checking the /rest/v1/users/current route.

As such, the returned top-level spaces are those visible to the specific user. We would recommend creating a dedicated user account, and a corresponding user API key, to give clarity about access rights in effect.

Dominic