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:
- When Relay reopens its windows after you quit, each window shows the workspace it had before.
- 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.
- 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:
| Tab | Contents |
|---|---|
| Variables | The workspace's variables and its environments. For Globals, the global variables. |
| Auth | The authentication that requests inherit. |
| Certs | Client certificates and trusted certificate authorities. |
| Cookies | The 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
- Creating and managing workspaces: Create, rename, switch between and delete workspaces.
- Organizing requests into collections: Group requests into collections and folders, and move, copy and style them.
- Using variables: Insert values into requests with
{{name}}tokens and see where each value comes from. - Storing a workspace in a folder: Keep a workspace as files in a folder you choose and share it with Git.