Collections & YAML Format

Collections & YAML Format

ApiArk stores everything as plain YAML files on your filesystem. No proprietary formats, no databases for your API definitions — just files you can read, edit, and version with Git.

---

Design Principles

1. One file per request — Each API request is a single .yaml file
2. Directory = Collection — The folder structure on disk IS your collection structure
3. Human-readable — Open any file in a text editor and understand it immediately
4. Git-friendly — YAML diffs are clean and meaningful
5. No UUIDs — The file path IS the identifier

---

Collection Structure

my-api-project/
├── .apiark/
│   ├── apiark.yaml                  # Collection configuration
│   ├── .env                         # Secrets (gitignored)
│   ├── .gitignore                   # Auto-generated
│   └── environments/
│       ├── development.yaml
│       ├── staging.yaml
│       └── production.yaml
├── users/
│   ├── _folder.yaml                 # Folder-level config (optional)
│   ├── get-all-users.yaml
│   ├── create-user.yaml
│   └── auth/
│       ├── login.yaml
│       └── refresh-token.yaml
└── products/
    ├── list-products.yaml
    └── create-product.yaml

Key Files

File	Purpose
.apiark/apiark.yaml	Collection name, version, defaults
.apiark/.env	Secret variables (auto-gitignored)
.apiark/environments/*.yaml	Environment definitions
_folder.yaml	Optional folder-level auth, scripts, headers
*.yaml	Individual API requests

---

Collection Config (apiark.yaml)

name: My API Project
version: 1

defaults:
  headers:
    Content-Type: application/json
    Accept: application/json
  auth:
    type: bearer
    token: "{{accessToken}}"
  sendCookies: true
  storeCookies: true
  persistCookies: false

---

Request File Format

Every request is a YAML file. Here's a complete example with all fields:

name: Create User
method: POST
url: "{{baseUrl}}/api/users"
description: Creates a new user account.

# Query parameters
params:
  include: profile
  verbose: "true"

# Request headers
headers:
  X-Request-ID: "{{$uuid}}"
  X-Custom-Header: my-value

# Authentication (overrides collection/folder auth)
auth:
  type: bearer
  token: "{{adminToken}}"

# Request body
body:
  type: json
  content: |
    {
      "name": "{{userName}}",
      "email": "{{userEmail}}",
      "role": "admin"
    }

# Declarative assertions
assert:
  status: 201
  body.id: { type: string }
  body.email: { eq: "{{userEmail}}" }
  responseTime: { lt: 2000 }

# Pre-request script
preRequestScript: |
  ark.env.set("userName", `User_${Date.now()}`);
  ark.env.set("userEmail", `user_${Date.now()}@example.com`);

# Post-response script
postResponseScript: |
  const body = ark.response.json();
  if (body.id) {
    ark.env.set("createdUserId", body.id);
  }

# JavaScript tests
tests: |
  ark.test("should return created user", () => {
    const body = ark.response.json();
    ark.expect(body).to.have.property("id");
    ark.expect(body.name).to.include("User_");
  });

  ark.test("should return 201", () => {
    ark.expect(ark.response.status).to.equal(201);
  });

# Saved response examples
examples:
  - name: Success
    status: 201
    headers:
      Content-Type: application/json
    body: |
      {"id": "usr_abc123", "name": "John Doe", "email": "john@example.com"}
  - name: Validation Error
    status: 422
    body: |
      {"error": "Email already exists"}

Minimal Request

Most fields are optional. A minimal request is just:

name: Health Check
method: GET
url: "{{baseUrl}}/health"

---

Body Types

# JSON
body:
  type: json
  content: '{"key": "value"}'

# XML
body:
  type: xml
  content: '<root><key>value</key></root>'

# Form Data (multipart)
body:
  type: formdata
  content:
    - key: file
      value: /path/to/file.png
      type: file
    - key: name
      value: "My File"
      type: text

# URL Encoded
body:
  type: urlencoded
  content:
    username: john
    password: "{{password}}"

# Raw Text
body:
  type: text
  content: "Hello, World!"

# Binary
body:
  type: binary
  path: /path/to/file.bin

# No body
body:
  type: none

---

Folder Config (_folder.yaml)

Optional file to set defaults for all requests in a folder:

name: User Endpoints
description: All user-related API endpoints

# Auth inherited by all requests in this folder
auth:
  type: bearer
  token: "{{userToken}}"

# Headers added to all requests in this folder
headers:
  X-API-Version: "2"

# Script runs before every request in this folder
preRequestScript: |
  console.log("Running user endpoint:", ark.info.requestName);

# Request execution order (for collection runner)
order:
  - login.yaml
  - get-profile.yaml
  - update-profile.yaml

---

Git Workflow

Since collections are just files, Git works naturally:

# Initialize a collection as a Git repo
cd my-api-project
git init
git add .
git commit -m "Initial API collection"

# The .gitignore auto-excludes secrets
cat .apiark/.gitignore
# .env
# *.secret

# Clean diffs when you change a request
git diff
# --- a/users/create-user.yaml
# +++ b/users/create-user.yaml
# @@ -3,7 +3,7 @@
#  url: "{{baseUrl}}/api/users"
# -  status: 200
# +  status: 201

# Branch per feature
git checkout -b feat/add-payment-endpoints

---

Format Versioning

The version field in apiark.yaml tracks the YAML schema version:

name: My API
version: 1

When ApiArk updates its format:

1. You'll see a dialog: "Upgrade collection format?"
2. Choose Upgrade (rewrites files) or Open Read-Only
3. Migrations are safe and reversible — your Git history is preserved

See Troubleshooting & FAQ for migration issues.