Dropbox API Tips: Working With Dropbox Namespaces

A Dropbox namespace is a collection of files and folders that are within a single shared folder, team folder, app folder, or within a team’s root folder or a user’s home folder. Namespaces provide the ability to access these types of folders and their contents without having to specify the entire path the folder is mounted to in each API request. This is beneficial since a folder’s path could differ between users for the same shared folder. Dropbox’s guide to namespaces provides an introduction to namespaces and how to access them via the API. Below, we dive into some of the details with accessing content in team folders and how to get started.

Accessing Team Folders

The first approach we took to access team folder data as a team member was to call the sharing/list_folders endpoint to retrieve a list of shared resources. Filtering out the items where is_team_folder is false lets us identify the team folders to retrieve further metadata on. However, using the folders’ namespace IDs like the Dropbox guide suggests returns a 404 error:

curl -X POST "https://api.dropboxapi.com/2/files/get_metadata" \
    --header 'Authorization: Bearer TOKEN' \
    --data '{"path":"ns:2744814537"}'

{
  "error_summary": "path/not_found/",
  "error": {
    ".tag": "path",
    "path": {
      ".tag": "not_found"
    }
  }
}

It turns out it isn’t possible to access namespaces that are not within the currently authenticated member’s home folder. To understand why, let’s look into the differences between a Dropbox root folder and home folder and what the Path Root represents.

Root vs. Home

For Dropbox Business users, each team shares a team space that all members can access. As a result, the folder layout and path to team space content is the same for each team member. The top-level folder for a team space is considered to be the “root,” representing the team’s root folder.

Team spaces allow two kinds of folders — team member folders and team folders.

Team member folders are individual members’ private folders, each representing a member’s “home” folder. These are private to that team member unless content within them is shared with other members or externally.

Team folders, however, are always shared with team members although each member may have different levels of permissions to the content within, such as read-only privileges.

To retrieve the root and home namespace IDs for a user, call the users/get_current_account endpoint. The excerpt shown below from the response provides an example of the type of identification information returned:

    {
      ...
      "root_info": {
        ".tag": "team",
        "root_namespace_id": "7",
        "home_namespace_id": "1",
        "home_path": "/Sarah"
      }
    }

The Path Root

The Dropbox API Path Root is the folder that an API request operates relative to. Including the Dropbox-API-Path-Root header, which enables apps to avoid including the namespace in each path referenced in API requests. By default, the Path Root in API requests is the currently authenticated member’s home folder. Since the home folder is within a team space, this makes it impossible to access other team folders that are at the same level as the home folders within a team space. To solve this, Dropbox allows API requests to set the Dropbox-API-Path-Root header to {".tag": "root", "root": ROOT_NAMESPACE_ID}to perform operations relative to the root folder instead of the default home folder. This JSON object format is referred to in the docs as the “root mode” of operation.

This solves the issue with the first API request above that resulted in a 404. Escalating the relative path root from the home folder to a team’s root folder enables the app to retrieve metadata for the team folder:

curl -X POST "https://api.dropboxapi.com/2/files/get_metadata" \     
  -H 'Authorization: Bearer TOKEN' \     
  -H 'Dropbox-API-Path-Root: {".tag": "root", "root": "2744814544"}' \
  -d '{"path":"ns:2744814537"}'

Let us know your thoughts in the comments!