Workspace Layout

A restful workspace is a directory containing a *.config.yaml file and supporting directories.

Directory Structure

my-workspace/
├── my-workspace.config.yaml    # Workspace definition
├── __main__.py                 # Entry point (adds root to sys.path)
├── apis/                       # Generated endpoint modules
│   └── my_api/
│       ├── __init__.py
│       └── endpoints.py        # Auto-generated Endpoint constants
├── notebooks/                  # User-written workflow scripts
│   ├── __init__.py
│   └── my_flow.py
└── .restful/                   # Runtime data (gitignored)
    ├── cache.json              # Token cache (per base_url)
    └── variables.json          # Workspace variables

Config File

The *.config.yaml file is the workspace marker. Workspace discovery walks up from the current directory until it finds one.

name: my-workspace
apis:
  - name: SFM Instance REST
    alias: sfm
    plugin: snf-instance-rest
    source: rbac_access_matrix.json
    base_url: https://100.94.115.90
    auth:
      type: bearer
      login_path: /security/v1/auth/login
      username: admin
      password_env: SFM_PASSWORD

APIs Directory

Each API gets its own subdirectory under apis/, named by sanitizing the API name to a valid Python identifier. The endpoints.py file is auto-generated by restful plugin load.

Notebooks Directory

Plain Python files with @stage-decorated functions. Stored in notebooks/ and executed by restful workflow run <name>.

.restful Directory

Runtime state that should not be committed to version control:

• cache.json — bearer tokens keyed by base URL, with JWT expiry timestamps
• variables.json — workspace-scoped key-value pairs set during workflow execution