Skip to main content
Workspaces in Yasumu are project-based directories that contain all your API testing definitions, configurations, and workflows. Unlike traditional API clients that store data in proprietary formats or cloud databases, Yasumu workspaces live directly in your file system using the Yasumu Schema Language (.ysl).

​
What is a workspace?

A workspace is a self-contained directory that stores:
  • REST API requests and collections
  • Environment variables and secrets
  • Email testing configurations
  • Groups and organizational structure
  • Workspace metadata and settings
Each workspace is completely independent and can be version controlled with Git, making collaboration seamless.

​
Directory structure

When you initialize a Yasumu workspace in a project, it creates a yasumu directory with the following structure: 
project-root/
└── yasumu/
    ├── workspace.ysl          # Workspace metadata and configuration
    ├── smtp.ysl               # SMTP server configuration
    ├── yasumu-lock.json       # Synchronization lock file
    ├── rest/                  # REST API entities
    │   ├── *.ysl              # Individual request files
    │   └── ...
    └── environment/           # Environment configurations
        ├── *.ysl              # Individual environment files
        └── ...
The yasumu-lock.json file is automatically managed by Yasumu for synchronization purposes. You should commit it to version control but avoid editing it manually.

​
Workspace configuration file

The main workspace.ysl file contains workspace-level metadata and organizational structure: 
@workspace

metadata {
  id: "v753h51r3e10zzcg5rkel8mv"
  name: "test-workspace"
  version: 0
}

snapshot 1768400471602

groups {
  w10lye9m7dsomdwoj9zooyf4: {
    id: "w10lye9m7dsomdwoj9zooyf4"
    name: "Media Test"
    entity: rest
    parentId: null
    workspaceId: "v753h51r3e10zzcg5rkel8mv"
  }
  kk0dm5udl71o00kykt03ftxa: {
    id: "kk0dm5udl71o00kykt03ftxa"
    name: "API Tests"
    entity: rest
    parentId: null
    workspaceId: "v753h51r3e10zzcg5rkel8mv"
  }
}

​
Workspace fields

Contains the workspace identifier, name, and version number.
  • id: Unique identifier for the workspace
  • name: Human-readable workspace name
  • version: Schema version for compatibility
Timestamp of the last synchronization, used for conflict resolution and change tracking.
Organizational structure for entities. Groups help organize REST requests, emails, and other entities into logical collections.
  • id: Unique identifier for the group
  • name: Group display name
  • entity: Type of entities in this group (e.g., rest)
  • parentId: Parent group ID for nested structures
  • workspaceId: Reference to the owning workspace

​
Working with workspaces

Yasumu provides a programmatic API for managing workspaces through the core library: 
import { Workspace } from '@yasumu/core';

// Access workspace properties
const workspace = new Workspace(manager, data);

console.log(workspace.name);      // Workspace name
console.log(workspace.path);      // File system path
console.log(workspace.createdAt); // Creation timestamp

// Access workspace modules
const restModule = workspace.rest;           // REST API testing
const environments = workspace.environments; // Environment management
const emails = workspace.emails;             // Email testing

// Synchronize workspace with file system
await workspace.synchronize();

​
Version control with Git

1

Initialize workspace

Create a new Yasumu workspace in your project directory.
2

Commit .ysl files

Add all .ysl files and the yasumu-lock.json to version control:
git add yasumu/
git commit -m "Add API testing workspace"
3

Collaborate with team

Team members can clone the repository and immediately access all API definitions:
git clone <repository-url>
cd project
# Open Yasumu and load the workspace
4

Review changes

Since .ysl files are plain text, you can review API changes in pull requests just like code:
request {
- url: "https://api.staging.example.com"
+ url: "https://api.production.example.com"
  headers: []
}
Never commit sensitive data like API keys or passwords to version control. Use environment secrets instead.

​
Workspace metadata

The Workspace class provides access to important metadata:

Identity

  • id: Unique identifier
  • name: Display name
  • path: File system location

Timestamps

  • createdAt: Creation date
  • updatedAt: Last modification
  • lastOpenedAt: Last access time

​
Best practices

Organize by feature: Create groups for different API domains or features to keep your workspace organized.
Use descriptive names: Give your workspace and groups clear, descriptive names that reflect their purpose.
Regular commits: Treat your API definitions like code—commit changes regularly with meaningful commit messages.
Separate environments: Use multiple environments (dev, staging, production) to test against different API endpoints without modifying requests.

​
Next steps

REST API Testing

Learn how to create and execute REST API requests

Environments

Configure environment variables and secrets

Schema Language

Deep dive into the .ysl format

Email Testing

Test email functionality with the catch-all SMTP server

Build docs developers (and LLMs) love

Get started for freeTalk to us