External Bodies

Load response bodies from external JSON or Excel files in moclojer. Perfect for large datasets, API proxies, and transforming spreadsheets into REST APIs with minimal configuration.

Instead of embedding large response bodies directly in YAML configuration files, moclojer supports loading responses from external files. This keeps your configuration clean and enables powerful use cases like transforming Excel spreadsheets into REST APIs or proxying remote endpoints.

🎯 Why Use External Bodies?

Problems with inline bodies:

❌ Large JSON responses make YAML files hard to read
❌ Difficult to maintain complex data structures
❌ Version control diffs become messy
❌ Can't reuse existing data files

Benefits of external bodies:

✅ Keep YAML configuration clean and readable
✅ Reuse existing JSON files and datasets
✅ Proxy remote APIs without duplication
✅ Transform Excel spreadsheets into APIs
✅ Separate concerns (config vs data)

flowchart LR
    A[HTTP Request] --> B[moclojer]
    B --> C{External Body?}
    C -->|Yes| D{Provider Type}
    C -->|No| E[Use inline body]
    D -->|json| F[Load JSON file]
    D -->|xlsx| G[Load Excel file]
    F --> H[Parse JSON]
    G --> I[Convert to JSON]
    H --> J[Return Response]
    I --> J
    E --> J

📝 Configuration

Replace body with external-body:

- endpoint:
    method: GET
    path: /api/products
    response:
      status: 200
      headers:
        Content-Type: application/json
      external-body:
        provider: json
        path: data/products.json

External Body Fields

Field

Required

Description

provider

Yes

File type: json or xlsx

path

Yes

File path (local or HTTP URL)

sheet-name

Excel sheet name (xlsx only)

🌍 Global Configuration

To avoid repeating the folder path in every endpoint, you can configure a global base folder for external bodies:

# Global configuration
- external-body:
    folder: data/responses

# Endpoints can now use relative paths
- endpoint:
    method: GET
    path: /api/users
    response:
      status: 200
      external-body:
        provider: json
        path: users.json  # Will resolve to: data/responses/users.json

- endpoint:
    method: GET
    path: /api/products
    response:
      status: 200
      external-body:
        provider: json
        path: products.json  # Will resolve to: data/responses/products.json

When to Use Global Configuration

Perfect for:

✅ Docker/Kubernetes deployments with mounted volumes
✅ Consistent folder structure across all endpoints
✅ Reducing configuration duplication
✅ Cleaner, more maintainable configuration

Example: Docker Compose Setup

# docker-compose.yml
services:
  moclojer:
    image: moclojer/moclojer:latest
    volumes:
      - ./config.yml:/config.yml
      - ./mock-data:/app/bodies  # Mount data directory
    command: --config /config.yml

# config.yml
- external-body:
    folder: /app/bodies  # All files loaded from here

- endpoint:
    method: GET
    path: /api/users
    response:
      external-body:
        provider: json
        path: users.json  # Loads from /app/bodies/users.json

Path Resolution Rules

When a global folder is configured:

Relative paths (e.g., users.json) → Combined with global folder
Absolute paths (e.g., /tmp/data.json) → Global folder is ignored
URLs (e.g., https://...) → Global folder is ignored

- external-body:
    folder: data/mocks

- endpoint:
    method: GET
    path: /relative
    response:
      external-body:
        provider: json
        path: users.json  # ✅ Resolves to: data/mocks/users.json

- endpoint:
    method: GET
    path: /absolute
    response:
      external-body:
        provider: json
        path: /tmp/users.json  # ✅ Uses absolute path as-is

- endpoint:
    method: GET
    path: /remote
    response:
      external-body:
        provider: json
        path: https://api.example.com/users  # ✅ URL works as-is

📄 JSON Provider

Local File

- endpoint:
    method: GET
    path: /api/users
    response:
      status: 200
      headers:
        Content-Type: application/json
      external-body:
        provider: json
        path: data/users.json

File: data/users.json

{
  "users": [
    {"id": 1, "name": "Alice", "email": "[email protected]"},
    {"id": 2, "name": "Bob", "email": "[email protected]"}
  ],
  "total": 2
}

Request:

curl http://localhost:8000/api/users

Response:

{
  "users": [
    {"id": 1, "name": "Alice", "email": "[email protected]"},
    {"id": 2, "name": "Bob", "email": "[email protected]"}
  ],
  "total": 2
}

Remote URL (API Proxy)

Proxy responses from real APIs:

- endpoint:
    method: GET
    path: /pokemon/:name
    response:
      status: 200
      headers:
        Content-Type: application/json
      external-body:
        provider: json
        path: https://pokeapi.co/api/v2/pokemon/{{path-params.name}}

Request:

curl http://localhost:8000/pokemon/pikachu

Response: (proxied from pokeapi.co)

{
  "name": "pikachu",
  "abilities": [...],
  "types": [...]
}

Template Variables in Paths

Use template variables to make paths dynamic:

- endpoint:
    method: GET
    path: /api/users/:userId/profile
    response:
      status: 200
      external-body:
        provider: json
        path: data/users/{{path-params.userId}}/profile.json

File structure:

data/
  users/
    1/
      profile.json
    2/
      profile.json

📊 Excel (XLSX) Provider

Transform Excel spreadsheets into REST APIs:

- endpoint:
    method: GET
    path: /api/employees
    response:
      status: 200
      headers:
        Content-Type: application/json
      external-body:
        provider: xlsx
        path: data/employees.xlsx
        sheet-name: Sheet1

Excel file: data/employees.xlsx

name

department

salary

Alice

Engineering

85000

Bob

Marketing

65000

Charlie

Sales

70000

Request:

curl http://localhost:8000/api/employees

Response:

[
  {"id": 1, "name": "Alice", "department": "Engineering", "salary": 85000},
  {"id": 2, "name": "Bob", "department": "Marketing", "salary": 65000},
  {"id": 3, "name": "Charlie", "department": "Sales", "salary": 70000}
]

Multiple Sheets

# Engineering department
- endpoint:
    method: GET
    path: /api/departments/engineering
    response:
      status: 200
      external-body:
        provider: xlsx
        path: company-data.xlsx
        sheet-name: Engineering

# Marketing department
- endpoint:
    method: GET
    path: /api/departments/marketing
    response:
      status: 200
      external-body:
        provider: xlsx
        path: company-data.xlsx
        sheet-name: Marketing

🌐 Real-World Use Cases

1. Product Catalog from Excel

Non-technical teams can update product data:

- endpoint:
    method: GET
    path: /api/v1/products
    response:
      status: 200
      external-body:
        provider: xlsx
        path: catalog/products-{{query-params.category|default:all}}.xlsx
        sheet-name: Products

Benefits:

Business team updates Excel directly
No code changes needed
Version control for data files
Easy imports from existing systems

2. Multi-Environment API Proxy

# Development: Use local mock data
- endpoint:
    method: GET
    path: /api/orders
    response:
      status: 200
      external-body:
        provider: json
        path: mocks/dev/orders.json

# Staging: Proxy to staging API
- endpoint:
    host: api-staging.example.com
    method: GET
    path: /api/orders
    response:
      status: 200
      external-body:
        provider: json
        path: https://api-staging.example.com/api/orders

# Production: Proxy to production API
- endpoint:
    host: api.example.com
    method: GET
    path: /api/orders
    response:
      status: 200
      external-body:
        provider: json
        path: https://api.example.com/api/orders

3. Testing with Real Data Samples

- endpoint:
    method: GET
    path: /api/test/users/:scenario
    response:
      status: 200
      external-body:
        provider: json
        path: test-data/{{path-params.scenario}}.json

File structure:

test-data/
  happy-path.json
  edge-cases.json
  error-scenarios.json
  large-dataset.json

4. Financial Reports from Spreadsheets

- endpoint:
    method: GET
    path: /api/reports/quarterly/:quarter
    response:
      status: 200
      headers:
        Content-Type: application/json
      external-body:
        provider: xlsx
        path: reports/Q{{path-params.quarter}}-2025.xlsx
        sheet-name: Summary

🔧 Advanced Patterns

Combining Template Variables and External Bodies

- endpoint:
    method: GET
    path: /api/:tenantId/config
    response:
      status: 200
      external-body:
        provider: json
        path: configs/{{path-params.tenantId}}/settings.json

Fallback to Inline Body

When file doesn't exist, use inline body as fallback:

# Primary: Try external file
- endpoint:
    method: GET
    path: /api/feature-flags
    response:
      status: 200
      external-body:
        provider: json
        path: features/{{header-params.Environment|default:dev}}.json

# Fallback: Default config
- endpoint:
    method: GET
    path: /api/feature-flags
    response:
      status: 200
      body: >
        {
          "features": {
            "newUI": false,
            "analytics": false
          }
        }

Conditional External Bodies

Use different files based on request:

- endpoint:
    method: GET
    path: /api/data
    response:
      status: 200
      external-body:
        provider: json
        path: data/{{query-params.version|default:v1}}/response.json

Requests:

curl http://localhost:8000/api/data              # uses data/v1/response.json
curl http://localhost:8000/api/data?version=v2  # uses data/v2/response.json

✅ Best Practices

Do:

✅ Use external bodies for responses > 50 lines
✅ Organize files in logical directories (data/, mocks/, fixtures/)
✅ Use meaningful file names (users.json, not data1.json)
✅ Version control your data files alongside config
✅ Use relative paths for portability
✅ Use global configuration when all files are in the same folder
✅ Document file structure in README

Don't:

❌ Mix local and remote paths without clear documentation
❌ Use absolute paths (breaks portability)
❌ Store sensitive data in external files (use environment variables)
❌ Forget to validate Excel sheet names (typos cause errors)
❌ Use external bodies for tiny responses (overkill)

📁 File Organization

Recommended Structure

project/
├── moclojer.yml              # Configuration
├── data/                     # External bodies
│   ├── users.json
│   ├── products.json
│   └── departments.xlsx
├── mocks/                    # Environment-specific
│   ├── dev/
│   │   └── orders.json
│   ├── staging/
│   │   └── orders.json
│   └── production/
│       └── orders.json
└── fixtures/                 # Test scenarios
    ├── happy-path.json
    └── edge-cases.json

🧪 Testing External Bodies

Verify File Paths

# Test if file is accessible
cat data/users.json

# Test if Excel file exists
ls -la data/employees.xlsx

Test with curl

# Local file
curl http://localhost:8000/api/users

# Remote proxy
curl http://localhost:8000/pokemon/pikachu

# Excel endpoint
curl http://localhost:8000/api/employees

Validate JSON Files

# Check JSON syntax
jq . data/users.json

# Pretty-print
jq '.' data/users.json

🔍 Debugging

Common Issues

Issue

Solution

File not found

Check path is relative to moclojer working directory

Excel sheet not found

Verify sheet name matches exactly (case-sensitive)

Invalid JSON

Validate file with jq or online validator

Remote URL timeout

Check network connectivity, increase timeout

Template variable not replaced

Ensure variable exists in request

Enable Debug Logging

MOCLOJER_LOG_LEVEL=debug moclojer --config moclojer.yml

Check File Paths

# Print current directory
- endpoint:
    method: GET
    path: /debug/cwd
    response:
      status: 200
      body: "Current working directory: {{env.PWD}}"

📊 Performance Considerations

Provider

File Size

Load Time

Caching

JSON (local)

< 1MB

< 10ms

Yes

JSON (remote)

< 1MB

100-500ms

No (fresh each time)

XLSX (local)

< 5MB

50-200ms

Yes

Tips:

Keep local JSON files under 1MB for fast responses
Use remote URLs sparingly (network latency)
Large Excel files (> 10MB) may slow startup time
Consider caching for frequently accessed remote URLs

🚨 Important Notes

Path Resolution: Paths are relative to the directory where moclojer is executed, not the config file location.

Remote URLs: Fetched on every request (no caching). Use for dynamic data or infrequently accessed endpoints.

Excel Limitations: Only .xlsx format supported (not .xls or .csv). First row must be headers.

Template Variables: Work in path field but not inside the loaded file content.

📚 See Also

Template Variables - Using variables in file paths
Path Parameters - Dynamic file loading
Multi-Domain Support - Different files per environment
Real-World Example - Complete examples

PreviousWebSocket Support NextWebhook Integration

Last updated 1 month ago

Was this helpful?

hashtag🎯 Why Use External Bodies?

hashtag📝 Configuration

hashtagExternal Body Fields

hashtag🌍 Global Configuration

hashtagWhen to Use Global Configuration

hashtagPath Resolution Rules

hashtag📄 JSON Provider

hashtagLocal File

hashtagRemote URL (API Proxy)

hashtagTemplate Variables in Paths

hashtag📊 Excel (XLSX) Provider

hashtagMultiple Sheets

hashtag🌐 Real-World Use Cases

hashtag1. Product Catalog from Excel

hashtag2. Multi-Environment API Proxy

hashtag3. Testing with Real Data Samples

hashtag4. Financial Reports from Spreadsheets

hashtag🔧 Advanced Patterns

hashtagCombining Template Variables and External Bodies

hashtagFallback to Inline Body

hashtagConditional External Bodies

hashtag✅ Best Practices

hashtag📁 File Organization

hashtagRecommended Structure

hashtag🧪 Testing External Bodies

hashtagVerify File Paths

hashtagTest with curl

hashtagValidate JSON Files

hashtag🔍 Debugging

hashtagCommon Issues

hashtagEnable Debug Logging

hashtagCheck File Paths

hashtag📊 Performance Considerations

hashtag🚨 Important Notes

hashtag📚 See Also

🎯 Why Use External Bodies?

📝 Configuration

External Body Fields

🌍 Global Configuration

When to Use Global Configuration

Path Resolution Rules

📄 JSON Provider

Local File

Remote URL (API Proxy)

Template Variables in Paths

📊 Excel (XLSX) Provider

Multiple Sheets

🌐 Real-World Use Cases

1. Product Catalog from Excel

2. Multi-Environment API Proxy

3. Testing with Real Data Samples

4. Financial Reports from Spreadsheets

🔧 Advanced Patterns

Combining Template Variables and External Bodies

Fallback to Inline Body

Conditional External Bodies

✅ Best Practices

📁 File Organization

Recommended Structure

🧪 Testing External Bodies

Verify File Paths

Test with curl

Validate JSON Files

🔍 Debugging

Common Issues

Enable Debug Logging

Check File Paths

📊 Performance Considerations

🚨 Important Notes

📚 See Also