Collections & YAML Format

Design Principles

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

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

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

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)

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

# 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

name: My API
version: 1