Files-first

The founding idea of API Craft: everything is a file. The OpenAPI spec, every request you save, your environment definitions, the mapping rules: all of it lives as plain JSON in your project's git repo. There is no proprietary workspace and no cloud account holding your work hostage.

What it means in practice

A project is just a directory you commit:

my-project/
├── .api-craft/
│   └── config.json          # project config
└── apis/
    ├── workflow/             # project-scoped workflows
    │   └── pet-lifecycle.json
    └── petstore-api/
        ├── api.json          # API metadata
        ├── spec.imported.json
        ├── schema.rules.json
        ├── resources/
        │   └── Pet/
        │       ├── _resource.json
        │       └── requests/
        │           └── get-pet.json
        ├── middlewares/      # before/after hooks, custom auth
        └── environments/
            ├── schema.json
            ├── dev.json
            └── dev.secrets.env   # gitignored

The desktop app and the craftr CLI both read and write these same files. Edit a request in the app and the file changes on disk; edit the file by hand and the app picks it up.

What it unlocks

• Review. Request and spec changes show up in git diff and go through pull requests like any other code.
• CI. Run requests from a pipeline with craftr; the project is already in the repo.
• Bulk edits. Rename a header across twenty requests with sed, or script changes in whatever language you like.
• Onboarding. git clone and open. No "export/import collection" dance, no shared workspace to join.
• No lock-in. It's your data, in a readable format, in your repo.

What stays out of git

Two things are deliberately gitignored: secrets (*.secrets.env) and the local cache (.api-craft/cache/, which holds response history). Everything else is meant to be committed and shared. See instance visibility for the one more nuance: personal and scratch requests that also stay local.