Skip to main content
Yasumu is designed for seamless team collaboration. All workspace data is stored as plain-text .ysl (Yasumu Schema Language) files that work perfectly with version control systems like Git.

​
Why Yasumu works great with teams

  • No cloud accounts required: Everything lives in your repository
  • Standard Git workflow: Commit, push, pull, branch, and merge like any other code
  • Readable diffs: .ysl files are text-based and produce clean, reviewable diffs
  • Secure by design: Secrets stay local, never committed to version control
  • Offline-first: No internet connection needed for collaboration
  • Version history: Full audit trail of all changes through Git

​
File structure for collaboration

When collaborating, your repository includes: 
my-project/
├── src/
├── tests/
├── yasumu/                    # Commit this directory
│   ├── workspace.ysl          # ✓ Commit
│   ├── smtp.ysl               # ✓ Commit
│   ├── yasumu-lock.json       # ✓ Commit
│   ├── rest/                  # ✓ Commit all .ysl files
│   │   ├── user-api.ysl
│   │   ├── auth-api.ysl
│   │   └── ...
│   └── environment/           # ⚠️ Commit structure, not secrets
│       ├── development.ysl    # ✓ Commit (without secret values)
│       ├── staging.ysl        # ✓ Commit (without secret values)
│       └── production.ysl     # ✓ Commit (without secret values)
└── .gitignore                 # Configure appropriately

​
Setting up collaboration

1

Initialize workspace

Create a workspace in your project directory:
cd my-project
# Open Yasumu and create workspace here
2

Create API collections

Build your REST requests, organize them into groups, and test them.
3

Set up environments

Create environments with variables, but keep secret values empty in shared environments:
@environment

metadata {
  id: "c10t47a2kufpq46wt9oomc4d"
  name: "Production"
}

variables [
  {
    key: "API_URL"
    value: "https://api.example.com"
    enabled: true
  },
]

secrets [
  {
    key: "API_TOKEN"
    value: ""  # Empty in version control
    enabled: true
  },
]
4

Configure .gitignore (optional)

While .ysl files are designed to be committed, you may want to exclude certain patterns:
# Keep this if you want to exclude local environment copies
yasumu/environment/local.ysl

# Yasumu lock file (similar to package-lock.json)
# Choose to commit or ignore based on your team's preference
# yasumu/yasumu-lock.json
5

Commit to Git

git add yasumu/
git commit -m "Add Yasumu workspace with API collections"
git push origin main
6

Team members clone and configure

Team members clone the repo and add their own secret values locally.

​
Managing secrets in teams

​
The secret management pattern

Yasumu separates variables (shared) from secrets (local): 
@environment

metadata {
  id: "env123"
  name: "Production"
}

variables [
  {
    key: "API_URL"
    value: "https://api.example.com"  # ✓ Shared with team
    enabled: true
  },
  {
    key: "API_VERSION"
    value: "v2"  # ✓ Shared with team
    enabled: true
  },
]

secrets [
  {
    key: "API_TOKEN"
    value: ""  # ✗ Empty in Git
    enabled: true
  },
  {
    key: "DATABASE_PASSWORD"
    value: ""  # ✗ Empty in Git
    enabled: true
  },
]

​
Sharing secret structure

Commit the secret keys (so the team knows what’s needed) but not the values: 
secrets [
  { key: "API_TOKEN", value: "", enabled: true },
  { key: "STRIPE_SECRET_KEY", value: "", enabled: true },
  { key: "DATABASE_PASSWORD", value: "", enabled: true },
]
Team members can see what secrets they need to configure locally.

​
Git workflow for Yasumu

​
Adding new requests

# Create new REST request in Yasumu
# A new .ysl file appears in yasumu/rest/

git add yasumu/rest/new-request.ysl
git commit -m "Add user profile endpoint"
git push

​
Updating existing requests

# Modify request in Yasumu
# The .ysl file is updated

git diff yasumu/rest/user-api.ysl
# Review the changes

git add yasumu/rest/user-api.ysl
git commit -m "Update user API endpoint URL"
git push

​
Creating feature branches

# Create feature branch
git checkout -b feature/payment-api

# Add payment-related requests in Yasumu
# Commit the new .ysl files

git add yasumu/rest/payment-*.ysl
git commit -m "Add payment API collection"
git push origin feature/payment-api

# Create pull request for team review

​
Reviewing changes

Because .ysl files are text-based, reviews are straightforward: 
@rest

metadata {
  name: "Get User"
- method: "GET"
+ method: "POST"
  id: "abc123"
}

request {
- url: "{{API_URL}}/user"
+ url: "{{API_URL}}/users/profile"
  headers: [
+   {
+     key: "Authorization"
+     value: "Bearer {{API_TOKEN}}"
+     enabled: true
+   },
  ]
}
Reviewers can:
  • See exactly what changed
  • Understand the API modifications
  • Suggest improvements
  • Approve or request changes

​
Team collaboration patterns

​
Shared base environments

Create base environments that the whole team uses: 
// Development environment (shared settings)
await workspace.environments.create({
  name: 'Development',
  variables: [
    { key: 'API_URL', value: 'http://localhost:3000', enabled: true },
    { key: 'DEBUG', value: 'true', enabled: true }
  ],
  secrets: [
    { key: 'API_TOKEN', value: '', enabled: true } // Empty in Git
  ]
});
Each team member fills in their own secrets locally.

​
Personal environments

Team members can create personal environments: 
// Create personal environment (not committed)
await workspace.environments.create({
  name: 'Alice-Local',
  variables: [
    { key: 'API_URL', value: 'http://localhost:4000', enabled: true }
  ],
  secrets: [
    { key: 'API_TOKEN', value: 'alice-dev-token', enabled: true }
  ]
});
Add personal environments to .gitignore: 
yasumu/environment/*-Local.ysl
yasumu/environment/personal-*.ysl

​
Standardized request groups

Organize requests into logical groups: 
// Create groups for different API sections
await workspace.rest.createEntityGroup({
  name: 'Authentication',
  entity: 'rest',
  parentId: null,
  workspaceId: workspace.id
});

await workspace.rest.createEntityGroup({
  name: 'User Management',
  entity: 'rest',
  parentId: null,
  workspaceId: workspace.id
});

await workspace.rest.createEntityGroup({
  name: 'Payments',
  entity: 'rest',
  parentId: null,
  workspaceId: workspace.id
});
This structure is shared across the team in workspace.ysl.

​
Synchronization and conflict resolution

​
Pulling team changes

# Pull latest changes
git pull origin main

# Yasumu automatically detects updated .ysl files
# Workspace is synchronized automatically

​
Handling merge conflicts

If two team members modify the same request: 
git pull origin main
# CONFLICT in yasumu/rest/user-api.ysl

# Open the file and resolve conflicts
# .ysl files are text-based, so standard Git merge tools work

git add yasumu/rest/user-api.ysl
git commit -m "Merge user API changes"

​
Avoiding conflicts

  • Communicate: Let team know what you’re working on
  • Small commits: Commit frequently to reduce conflict likelihood
  • Feature branches: Use branches for experimental changes
  • Clear naming: Use descriptive names for requests and environments

​
Programmatic collaboration workflows

​
Workspace synchronization

// Manually trigger workspace sync after Git pull
await workspace.synchronize();

console.log('Workspace synchronized with latest changes');

​
Validating workspace structure

// Check for required environments
const environments = await workspace.environments.list();
const requiredEnvs = ['Development', 'Staging', 'Production'];

for (const envName of requiredEnvs) {
  const exists = environments.some(e => e.name === envName);
  if (!exists) {
    console.warn(`Missing environment: ${envName}`);
  }
}

// Check for missing secret values
const active = await workspace.environments.getActiveEnvironment();
if (active) {
  const secrets = active.secrets.toJSON();
  for (const secret of secrets) {
    if (secret.enabled && !secret.value) {
      console.warn(`Secret not configured: ${secret.key}`);
    }
  }
}

​
Onboarding automation

// Script to help new team members set up their environment

async function setupDeveloperEnvironment() {
  const yasumu = new Yasumu();
  const workspace = await yasumu.workspaces.open({ id: 'workspace-id' });
  const env = await workspace.environments.get('development-env-id');

  if (!env) {
    console.error('Development environment not found');
    return;
  }

  // Prompt for required secrets
  const apiToken = prompt('Enter your API token: ');
  const dbPassword = prompt('Enter database password: ');

  // Set secrets
  await env.secrets.set('API_TOKEN', apiToken);
  await env.secrets.set('DATABASE_PASSWORD', dbPassword);

  console.log('✓ Environment configured successfully!');
}

​
Documentation and onboarding

​
Team documentation

Create a YASUMU.md in your repository: 
# Yasumu Setup

## Getting Started

1. Install Yasumu: https://yasumu.dev/download
2. Clone this repository
3. Open Yasumu and load the workspace from this directory
4. Configure your secrets (see below)

## Required Secrets

Set these secrets in your local environment:

- `API_TOKEN`: Get from https://dashboard.example.com/tokens
- `DATABASE_PASSWORD`: Ask team lead
- `STRIPE_SECRET_KEY`: Available in 1Password

## Environments

- **Development**: Local development (http://localhost:3000)
- **Staging**: Staging server (https://staging.example.com)
- **Production**: Production server (https://api.example.com)

## Common Workflows

- Testing auth: Run requests in "Authentication" group
- User CRUD: See "User Management" group
- Payment flow: Check "Payments" group

​
Best practices for teams

​
Communication

  • Announce changes: Let the team know about major API changes
  • Document decisions: Use Git commit messages to explain why
  • Review together: Use pair programming for complex API workflows

​
Organization

  • Consistent naming: Agree on naming conventions for requests and environments
  • Logical grouping: Organize requests by feature or domain
  • Clean structure: Regularly review and refactor request organization

​
Security

  • Never commit secrets: Always keep secret values empty in Git
  • Rotate regularly: Update shared secrets periodically
  • Access control: Use Git repository permissions to control access
  • Audit trail: Review Git history for secret-related changes

​
Maintenance

  • Remove obsolete requests: Delete outdated API requests
  • Update documentation: Keep environment setup docs current
  • Sync regularly: Pull latest changes frequently
  • Test before pushing: Verify requests work before committing

​
Troubleshooting

​
Secret values not persisting

If secrets reset after Git operations:
  1. Ensure secret values are set after pulling changes
  2. Check that .ysl files aren’t being overwritten
  3. Consider using personal environment files not tracked by Git

​
Workspace not loading after pull

// Force workspace synchronization
await workspace.synchronize();

// Or reload workspace
const yasumu = new Yasumu();
const workspace = await yasumu.workspaces.open({ id: 'workspace-id' });

​
Merge conflicts in .ysl files

Resolve like any text file:
  1. Open the file in your editor
  2. Look for conflict markers (<<<<<<<, =======, >>>>>>>)
  3. Choose which changes to keep
  4. Remove conflict markers
  5. Commit the resolution

​
Next steps

Creating workspaces

Learn about workspace structure

Environment variables

Master environment configuration

Build docs developers (and LLMs) love

Get started for freeTalk to us