Skip to main content
Yasumu takes a fundamentally different approach to API client data storage. Instead of proprietary databases or cloud-based solutions, everything lives in your project folder as plain .ysl (Yasumu Schema Language) files that you can commit, diff, and review like any other code.

​
Why Git-friendly matters

Traditional API clients store collections in binary formats or require cloud accounts, creating friction for version control and team collaboration. Yasumu eliminates these barriers:

No cloud required

All data stored locally in your project

Version control

Commit API collections alongside your code

Code reviews

Review API changes in pull requests

Team sync

Share collections via Git, no accounts needed

​
The .ysl file format

Yasumu uses a custom schema language designed for both machine readability and clean Git diffs: 
@rest

metadata {
  name "Create User"
  method "POST"
  id "usr_create_001"
  groupId "user_management"
}

request {
  url "https://api.example.com/users"
  headers [
    { key "Content-Type" value "application/json" enabled true }
    { key "Authorization" value "Bearer {{token}}" enabled true }
  ]
  parameters []
  searchParameters []
  body {
    type "json"
    content "{
      \"name\": \"{{userName}}\",
      \"email\": \"{{userEmail}}\"
    }"
  }
}

dependencies []

script {
  export function onRequest(req) {
    // Pre-request logic
    req.headers.set('X-Request-ID', crypto.randomUUID());
  }
}

test {
  export function onTest(req, res) {
    expect(res.status).toBe(201);
    expect(res.json().id).toBeDefined();
  }
}

​
Format benefits

The .ysl format uses a clear block-based structure that’s easy to read and understand. Each section (metadata, request, script, test) is clearly delineated.
Changes to individual fields produce minimal, focused diffs. Adding a header or modifying a URL creates a small, reviewable change:
request {
  url "https://api.example.com/users"
  headers [
    { key "Content-Type" value "application/json" enabled true }
+   { key "X-API-Version" value "2024-01" enabled true }
  ]
}
The structured format reduces merge conflicts. Changes to different requests or different sections of the same request can be merged automatically.
Yasumu’s schema parser validates .ysl files during load, catching syntax errors early:
ysl.service.ts:10-22
public serialize<T extends AnyYasumuSchema>(schema: T, value: Infer<T>) {
  return serialize(value, schema);
}

public deserialize<T extends AnyYasumuSchema>(schema: T, content: string) {
  return deserialize(content, schema);
}

​
Workspace structure

When you initialize Yasumu in a project, it creates a standardized directory structure: 
your-project/
├── yasumu/
│   ├── workspace.ysl          # Workspace configuration
│   ├── rest/
│   │   ├── auth/
│   │   │   ├── login.ysl
│   │   │   └── register.ysl
│   │   ├── users/
│   │   │   ├── get-user.ysl
│   │   │   ├── create-user.ysl
│   │   │   └── update-user.ysl
│   │   └── posts/
│   │       └── list-posts.ysl
│   ├── environments/
│   │   ├── development.ysl
│   │   ├── staging.ysl
│   │   └── production.ysl
│   └── smtp/
│       └── smtp.ysl            # SMTP server configuration
└── .git/
The entire yasumu/ directory can be committed to version control, making your API collections part of your codebase.

​
Git workflow

​
Initial setup

1

Initialize workspace

Create a new Yasumu workspace in your project directory
2

Create .gitignore

Add workspace-specific exclusions:
.gitignore
# Yasumu - commit the workspace structure
yasumu/

# But exclude local-only files
!yasumu/workspace.ysl
!yasumu/rest/
!yasumu/environments/
!yasumu/smtp/

# Exclude environment secrets (values stored separately)
yasumu/environments/*.local.ysl

# SQLite database (auto-synced from .ysl files)
yasumu/*.db
yasumu/*.db-*
3

Commit structure

git add yasumu/
git commit -m "feat: add API collection for user management"

​
Making changes

Changes to API requests are reflected immediately in .ysl files: 
# 1. Update request in Yasumu UI
# 2. View changes
git diff yasumu/rest/users/create-user.ysl

# 3. Commit changes
git add yasumu/rest/users/create-user.ysl
git commit -m "feat: add user role validation to create endpoint"

​
Team collaboration

Yasumu’s Git integration enables seamless team workflows:

​
Pull request reviews

API changes are reviewed just like code: 
@rest

metadata {
  name "Get User Profile"
  method "GET"
  id "usr_profile_001"
  groupId "user_management"
}

request {
- url "https://api.example.com/profile"
+ url "https://api.example.com/v2/users/{{userId}}/profile"
  headers [
    { key "Authorization" value "Bearer {{token}}" enabled true }
+   { key "X-API-Version" value "2.0" enabled true }
  ]
+  parameters [
+    { key "userId" value "{{currentUserId}}" enabled true }
+  ]
}

+test {
+  export function onTest(req, res) {
+    expect(res.status).toBe(200);
+    expect(res.json()).toHaveProperty('email');
+    expect(res.json()).toHaveProperty('name');
+  }
+}
Reviewers can:
  • See exactly what changed in the API request
  • Comment on specific changes
  • Suggest improvements to scripts or tests
  • Verify endpoint URLs and parameters

​
Syncing with teammates

1

Fetch latest changes

git pull origin main
Yasumu automatically detects changes and reloads the workspace.
2

Review new requests

New requests added by teammates appear in your workspace immediately.
3

Resolve conflicts

If conflicts occur in .ysl files, resolve them like any other text file:
request {
<<<<<<< HEAD
  url "https://api-staging.example.com/users"
=======
  url "https://api.example.com/v2/users"
>>>>>>> feature/api-v2
}
4

Test changes

Run the updated requests to verify they work in your environment.

​
Environment secrets

Yasumu separates configuration from secrets for security:
development.ysl
@environment

metadata {
  id "env_dev_001"
  name "Development"
}

variables [
  { key "apiUrl" value "https://api-dev.example.com" enabled true }
  { key "apiVersion" value "v2" enabled true }
]

secrets [
  { key "apiKey" value "" enabled true }
  { key "authToken" value "" enabled true }
]
Secret values are never stored in .ysl files. They remain empty in version control and are populated locally from environment variables or secure vaults.

​
Managing secrets

.env.local
# Not committed to Git
YASUMU_SECRET_apiKey=sk_live_abc123...
YASUMU_SECRET_authToken=eyJhbGc...

​
Synchronization

Yasumu maintains a local SQLite database for performance, synchronized with .ysl files:
synchronization.service.ts:118-200
// Yasumu watches for file changes
if (entry.isFile && entry.name.endsWith('.ysl')) {
  // Parse and sync to database
  const parsed = this.yslService.deserialize(RestSchema, fileContent);
}

// Database changes write back to .ysl files
const content = this.yslService.serialize(RestSchema, entityData);
await this.yslService.emit(content, join(restDir, `${entity.id}.ysl`));
Synchronization features:
  • Bidirectional sync: Changes in UI or files are reflected in both
  • Conflict detection: Detects and resolves conflicts between file and database
  • Lock files: Prevents concurrent modification issues
  • Auto-reload: Workspace reloads automatically when files change
The database is never committed to Git. It’s automatically rebuilt from .ysl files when you clone the repository or switch branches.

​
Best practices

Commit related changes together

Group related API changes in a single commit with descriptive messages

Use feature branches

Create branches for new API integrations or major endpoint changes

Review before merging

Always review .ysl changes in pull requests to catch errors

Keep environments separate

Maintain separate environment files for dev, staging, and production

Document breaking changes

Use commit messages to document API version changes or breaking updates

Sync regularly

Pull latest changes frequently to stay in sync with your team

​
Migration from other tools

Yasumu can import collections from other API clients while converting them to .ysl format: 
// Import from Postman collection
await workspace.importCollection('postman', '/path/to/collection.json');

// Collections are converted to .ysl files automatically
// Ready to commit to Git
After import, you can immediately commit the generated .ysl files to version control.

Build docs developers (and LLMs) love

Get started for freeTalk to us