06 - Library and File Storage
Library Root Concept
API Freeman stores saved requests in a user-selected local folder called the library root.
The selected root path is persisted in Electron userData settings:
- settings file:
settings.json - key:
libraryPath
What Is Stored in the Library
Inside the root, the app stores:
- Request YAML files (one per request)
- Optional body sidecar files
- Folder variable config files
Request File Detection Rules
During tree scanning, a file is treated as a request file if it ends with:
.request.yaml.request.yml
Dot-prefixed filesystem entries are ignored during scan.
Folder Config File Names
Current folder variable file name:
.apifreeman-folder.yaml
Legacy-compatible fallback while reading:
.anti-postman-folder.yaml
Writes always use the new name.
Save Behavior
When saving a request:
- Target folder is created if needed.
- File name is generated from request name slug.
- If duplicate mode is on, unique suffix is added when needed.
- YAML request document is written.
- If body text exists, sidecar body file is written.
- Old body files are cleaned up when renaming/changing body reference.
Slug and Naming
Request names are slugified:
- normalized to ASCII
- lowercased
- non-alphanumeric collapsed to
-
If empty after slugify, fallback is request.
Body Sidecar File Extensions
Extension is inferred from content type:
- json ->
.json - xml ->
.xml - html ->
.html - everything else ->
.txt
Body sidecar naming pattern:
<request-basename>.body.<ext>
Tree Snapshot Model
The renderer receives snapshots containing:
- libraryPath
- tree of folders and request summaries
Each request summary includes:
- id
- name
- method
- url
- relativePath
- folderPath
- optional source metadata
Rename and Delete Behavior
Rename:
- Folder rename renames path on disk
- Request rename is implemented as save flow with updated name/path
Delete:
- Deleting request also removes linked body sidecar file (if present)
- Deleting folder removes folder recursively
Path Safety
Storage helpers enforce root boundary checks:
- Any resolved path must remain inside configured root
- Access outside root throws error
This protects against accidental traversal beyond the chosen library folder.