Workspace Management

​

What is a Workspace?

​

Key Characteristics

• Independent Storage - Separate local directory for all data
• Isolated Data - Collections and environments don’t mix between workspaces
• Git Configuration - Optional Git repository for sync and collaboration
• Custom Settings - Workspace-specific preferences and defaults
• Quick Switching - Seamlessly switch between different contexts

​

Why Use Multiple Workspaces?

​

Separation of Concerns

Personal Workspace
├── Side projects
├── Learning APIs
└── Experiments

Work Workspace
├── Company APIs
├── Internal services
└── Production endpoints

Client-X Workspace
├── Client APIs
├── Integration tests
└── Documentation

​

Team Collaboration

• Team A syncs to github.com/company/team-a-apis
• Team B syncs to github.com/company/team-b-apis
• Personal stays local or syncs to private repo

​

Environment Management

• Development - Local and dev server APIs
• Staging - Pre-production testing
• Production - Live production APIs

​

Workspace Components

​

Collections

workspace/collections/
├── rest/
│   ├── users-api.json
│   ├── products-api.json
│   └── orders-api.json
├── graphql/
│   └── main-api.json
└── realtime/
    └── websocket-api.json

​

Environments

workspace/environments/
├── development.json
├── staging.json
├── production.json
└── local.json

​

History

workspace/history/
├── rest.json
├── graphql.json
└── realtime.json

​

Settings

{
  "name": "My Workspace",
  "description": "Personal API projects",
  "defaultEnvironment": "development",
  "git": {
    "enabled": true,
    "remote": "[email protected]:user/my-apis.git",
    "branch": "main",
    "autoSync": true,
    "syncInterval": 300
  }
}

​

Creating Workspaces

​

From Welcome Screen

1. Enter workspace name
2. Choose storage location
3. Optionally configure Git
4. Start using Auk

​

From Workspace Selector

​

Quick Create

• macOS: Cmd + Shift + N
• Windows/Linux: Ctrl + Shift + N

​

Switching Workspaces

​

Using Workspace Selector

1. Click workspace name in top bar
2. Select workspace from dropdown
3. Auk loads the selected workspace

​

Keyboard Shortcuts

• Next Workspace: Cmd/Ctrl + ]
• Previous Workspace: Cmd/Ctrl + [
• Workspace Switcher: Cmd/Ctrl + Shift + W

​

Recent Workspaces

• Last 5 workspaces shown at top of selector
• Quick access to frequently used workspaces
• Sorted by last access time

​

Workspace Settings

​

Basic Information

• Display name shown in workspace selector
• Can be changed anytime
• Should be descriptive and unique

• Optional longer description
• Helps identify workspace purpose
• Shown in workspace selector tooltip

• Local directory path
• Cannot be changed after creation
• Should be easily accessible

​

Git Configuration

• Toggle Git synchronization on/off
• Can be enabled/disabled anytime
• Requires Git repository setup

• Git repository URL
• SSH or HTTPS format
• Can be changed if needed

• Default branch to use
• Usually main or master
• Can switch branches anytime

• Automatic synchronization interval
• Options: 5min, 15min, 30min, 60min, manual
• Balances freshness vs. performance

• SSH keys (recommended)
• HTTPS with token
• OAuth (coming soon)

​

Default Settings

• Environment loaded on workspace open
• Useful for consistent workflow
• Can be changed per session

• Automatically save changes
• Interval: 30s, 1min, 5min, manual
• Prevents data loss

• Maximum history entries to keep
• Options: 50, 100, 500, 1000, unlimited
• Older entries automatically removed

​

Workspace Organization Strategies

​

By Project

├── Project Alpha
│   ├── Backend APIs
│   ├── Frontend APIs
│   └── Mobile APIs
├── Project Beta
│   ├── Core Services
│   └── Integration APIs
└── Project Gamma
    └── Microservices

• Clear project boundaries
• Easy to share entire project
• Independent Git repositories

• More workspaces to manage
• Switching between projects

​

By Environment

├── Development
│   ├── All dev APIs
│   └── Local services
├── Staging
│   ├── Pre-prod APIs
│   └── Integration tests
└── Production
    ├── Live APIs
    └── Monitoring

• Environment isolation
• Prevents accidental prod changes
• Clear context switching

• Duplicate collections
• More maintenance

​

By Team

├── Frontend Team
│   ├── UI APIs
│   └── Client services
├── Backend Team
│   ├── Core APIs
│   └── Database services
└── DevOps Team
    ├── Infrastructure APIs
    └── Monitoring

• Team collaboration
• Shared Git repository
• Clear ownership

• Requires coordination
• Potential conflicts

​

Hybrid Approach

├── Work
│   ├── Project-A-Dev
│   ├── Project-A-Prod
│   ├── Project-B-Dev
│   └── Project-B-Prod
└── Personal
    ├── Learning
    ├── Side-Projects
    └── Experiments

​

Data Isolation

​

Complete Separation

• Collections - No sharing between workspaces
• Environments - Independent variable sets
• History - Separate request history
• Settings - Workspace-specific configuration

​

Benefits

1. No Conflicts - Changes in one workspace don’t affect others
2. Clean Organization - Each workspace is self-contained
3. Easy Backup - Backup individual workspaces
4. Flexible Sharing - Share specific workspaces via Git

​

Sharing Data

Workspace A → Export Collection → Workspace B → Import

Workspace A → Push to Git → Workspace B → Pull from Git

cp workspace-a/collections/api.json workspace-b/collections/

​

Workspace Maintenance

​

Regular Tasks

• Review and clean up old requests
• Update environment variables
• Sync with Git repository

• Archive unused collections
• Review workspace organization
• Update documentation

• Evaluate workspace structure
• Consider consolidation or splitting
• Backup important data

​

Cleanup

1. Export important data
2. Delete workspace
3. Clean up Git repository (if needed)

# Create archive
tar -czf workspace-archive-2024.tar.gz ~/Documents/Auk/old-workspace

# Move to archive location
mv workspace-archive-2024.tar.gz ~/Archives/

​

Troubleshooting

​

Workspace Not Loading

1. Check if storage directory exists
2. Verify directory permissions
3. Check for corrupted files
4. Restore from Git backup

​

Slow Performance

1. Reduce history limit
2. Archive old collections
3. Disable auto-sync temporarily
4. Check disk space

​

Git Sync Issues

1. Check network connection
2. Verify Git credentials
3. Pull latest changes manually
4. Resolve conflicts

​

Data Loss

1. Check workspace path in settings
2. Look for backup in Git repository
3. Check system trash/recycle bin
4. Restore from manual backup

​

Best Practices

​

Naming Conventions

✅ Good:
- "Company APIs - Production"
- "Client-X Integration"
- "Personal Learning Projects"

❌ Bad:
- "Workspace 1"
- "Test"
- "New Workspace"

​

Git Repository Structure

company-apis/
├── team-a/
│   └── workspace-data/
├── team-b/
│   └── workspace-data/
└── shared/
    └── common-collections/

​

Documentation

# Workspace: Company APIs

## Purpose
Production APIs for company services

## Environments
- Development: dev.company.com
- Staging: staging.company.com
- Production: api.company.com

## Team
- Owner: @john
- Contributors: @jane, @bob

## Last Updated
2024-02-20

​

Security

1. Use Secret Variables - Don’t commit secrets to Git
2. Separate Workspaces - Keep prod separate from dev
3. Access Control - Use private Git repositories
4. Regular Audits - Review who has access

​

Next Steps