12 - File Format Reference

This document describes on-disk formats used by API Freeman.

1) Request Document

File naming:

• *.request.yaml (or *.request.yml)

Required base shape:

schemaVersion: 1
kind: request
id: 8f8f8f8f-1111-2222-3333-444444444444
name: Get Users
method: GET
url: "{{baseUrl}}/users"
params:
  - key: page
    value: "1"
headers:
  - key: Accept
    value: application/json
body: null

Optional fields:

• source (manual/openapi/postman metadata)
• preRequestScript
• testScript

Body Reference Variant

When body exists, document stores body reference:

body:
  contentType: application/json
  file: get-users.body.json

2) Body Sidecar File

Stored as plain text in same folder as request file. Extension is inferred from content type:

• .json, .xml, .html, .txt

Example get-users.body.json:

{
  "limit": 25,
  "active": true
}

3) Folder Variable Document

New file name:

• .apifreeman-folder.yaml

Legacy read compatibility:

• .anti-postman-folder.yaml

Shape:

schemaVersion: 1
kind: folder
variables:
  - key: baseUrl
    value: https://api.example.com
  - key: token
    value: abc123

4) Source Metadata: OpenAPI

Example source block for imported OpenAPI request:

source:
  kind: openapi
  sourceType: file
  sourceIdentity: file:petstore.yaml
  sourceLabel: petstore.yaml
  specTitle: Petstore API
  operationKey: "GET /pets"
  operationId: listPets
  path: /pets
  method: GET
  tag: Pets

5) Source Metadata: Postman

Example source block for imported Postman request:

source:
  kind: postman
  sourceType: file
  sourceIdentity: file:collection.json
  sourceLabel: collection.json
  collectionName: Team Collection
  itemKey: users/get-users
  itemPath:
    - users
    - Get Users
  method: GET

6) User Settings File

Electron userData settings file stores library path:

{
  "libraryPath": "C:/path/to/library"
}

7) Snapshot/Data Transfer Models

In-memory and IPC transfer structures are defined in src/lib/contracts.ts. For developers, this file is the source of truth for:

• Request payload models
• Response payload models
• Library tree/snapshot models
• Import preview/result models