Workspaces and Collections

Understanding workspaces

Learn how workspaces, collections, folders and drafts fit together.

Overview

A workspace holds everything for one project or API. Each Relay window shows one workspace, and you can open several windows to work in different workspaces side by side.

A workspace contains:

  • Collections: Groups of saved requests, such as the endpoints of one API. Collections can contain folders, and folders can contain more folders.
  • Environments: Named sets of variables, such as Development and Production. One environment at a time can be active.
  • Variables: Values that every request in the workspace can use as {{name}} tokens.
  • Authentication: The credentials that requests in the workspace inherit unless a collection, folder or request sets its own.
  • Certificates: Client certificates to present and certificate authorities to trust.
  • Cookies: The cookies the workspace's requests have received and send back.
  • Settings: Defaults for the timeout, redirects, proxy and certificate checks.

Collections and folders can carry their own variables, authentication, scripts and settings, which the requests inside them inherit. For more information, see Configuring collections and folders.

Understand drafts and history

Drafts and history aren't part of any one workspace's collections. The sidebar lists them in every window, whichever workspace it shows.

  • Drafts: Requests you haven't saved to a collection. A new draft belongs to the workspace of the window you create it in, and it uses that workspace's variables, environment and authentication, but no collection's or folder's. To keep a draft with related requests, save it to a collection.
  • History: Every request you've sent, from any workspace, newest first. For more information, see Reviewing request history.

Drafts and history stay on your Mac. When you keep a workspace in a folder and share it, they aren't part of the files you share.

Switch workspaces in a window

The workspace menu at the top of the sidebar shows the name of the window's workspace. Click it to see these sections:

  • Workspace: Every workspace. Choose one to show it in the window.
  • Environment: No Environment and each of the workspace's environments. Choose one to make it active.

Below them are New Workspace…, Open Workspace… and Edit Workspaces….

Switching workspaces changes only the current window. Other windows keep showing their own workspaces.

A new window starts on a workspace in this order:

  1. When Relay reopens its windows after you quit, each window shows the workspace it had before.
  2. A window you open with File > New Window, File > New Tab or Open in New Window starts on the workspace of the window you opened it from. Open in New Window on a request in a collection uses that request's workspace.
  3. Otherwise, a window starts on the workspace you used last.

Edit workspaces and globals

Choose Edit Workspaces… from the workspace menu to open the Workspaces window. Its sidebar lists Globals and then each workspace. Select one and use the tabs in the toolbar:

TabContents
VariablesThe workspace's variables and its environments. For Globals, the global variables.
AuthThe authentication that requests inherit.
CertsClient certificates and trusted certificate authorities.
CookiesThe workspace's cookies. Cookies always belong to a workspace, so Globals has none.
Settings (gear)Request settings defaults. For a workspace, also where it's stored.

Globals apply to every workspace. A global variable is available to every request unless a workspace, environment, collection or folder defines the same name, and global authentication applies wherever nothing closer sets it.

The Workspaces window has its own undo history, separate from the main windows.

See Also