Mini Wrekenfile

What is a Mini Wrekenfile?

A Mini Wrekenfile is a lightweight, simplified version of a full Wrekenfile. It focuses on the core I/O mapping and method signatures of an API without including the full OpenAPI-like details like complex schemas, examples, or nested structures.

Mini Wrekenfiles are designed for:

Quick ingestion by LLMs and AI agents
Lightweight transport for embeddings or workflow generation
Simplified API discovery for workflow automation
Rapid prototyping and API exploration

Key Characteristics

Lightweight Structure

Mini Wrekenfiles keep only the essentials:

Service identification (name, version)
Method definitions with basic I/O
Simple type definitions (no complex schemas)
Minimal metadata for AI understanding

Typical Structure

service: Stripe
version: "2.0.2"

methods:
  - name: create_charge
    method: POST
    path: /v1/charges
    input:
      amount: number
      currency: string
      source: string
    output:
      id: string
      status: string

Mini vs Full Wrekenfile

Feature	Mini Wrekenfile	Full Wrekenfile
Focus	Lightweight I/O & method metadata	Full API semantics
Purpose	AI understanding & workflow generation	Full API fidelity
Schema support	Minimal (flat types)	Full nested schema support
Size	Very small (1–5 KB)	Large (50 KB+)
Usage	LLM training / MCP / AI workflows	SDK generation / validation

Use Cases

🤖 AI Agent Integration

Feeding API summaries to Swytchcode Playground or MCP
Quick API understanding for workflow generation
Storing embeddings in vector databases for retrieval

Development Workflow

Quick Wrekenfile previews during onboarding
Rapid API exploration before full spec conversion
Lightweight API documentation

📡 Dynamic Loading

Sharing "mini" specs via REST for dynamic AI agent loading
Real-time API discovery in microservice architectures
Quick API integration in CI/CD pipelines

Complete Examples

Here are comprehensive examples demonstrating various use cases and patterns:

Example 1: E-commerce API - Product Management

service: EcommerceAPI
version: "2.0.2"
base_url: "https://api.shop.com"

methods:
  - name: create_product
    method: POST
    path: /products
    auth: bearer_token
    input:
      name: string
      description: string
      price: number
      currency: string
      category_id: number
      images: "array[string]"
      inventory_count: number
      tags: "array[string]"
    output:
      product_id: string
      name: string
      price: number
      currency: string
      created_at: timestamp
      status: string
    errors:
      - code: 400
        message: "Invalid product data"
      - code: 401  
        message: "Unauthorized access"
      - code: 409
        message: "Product already exists"

  - name: get_product
    method: GET
    path: /products/:product_id
    input:
      product_id: string
    output:
      product_id: string
      name: string
      description: string
      price: number
      currency: string
      category: object
      images: "array[string]"
      inventory_count: number
      tags: "array[string]"
      created_at: timestamp
      updated_at: timestamp

  - name: list_products
    method: GET
    path: /products
    input:
      page: number
      limit: number
      category: string
      min_price: number
      max_price: number
      search: string
    output:
      products: "array[object]"
      pagination: object
      total_count: number
      filters_applied: object

Example 2: User Management SDK - Authentication Flow

service: UserSDK
version: "2.0.2"
execution_type: sdk
client_class: UserClient

methods:
  - name: register_user
    sdk_method: registerUser
    execution: async
    input:
      email: string
      password: string
      first_name: string
      last_name: string
      phone: string
      preferences: object
    output:
      user_id: string
      email: string
      first_name: string
      last_name: string
      verification_required: boolean
      access_token: string
      refresh_token: string
      expires_in: number
    errors:
      - type: ValidationError
        message: "Invalid email or password format"
      - type: ConflictError
        message: "User already exists"

  - name: login_user
    sdk_method: loginUser
    execution: async
    input:
      email: string
      password: string
      remember_me: boolean
    output:
      user_id: string
      access_token: string
      refresh_token: string
      expires_in: number
      user_profile: object

  - name: update_profile
    sdk_method: updateProfile
    execution: async
    requires_auth: true
    input:
      user_id: string
      first_name: string
      last_name: string
      phone: string
      avatar_url: string
      preferences: object
    output:
      user_profile: object
      updated_at: timestamp

Example 3: File Storage API - Upload and Management

service: FileStorageAPI
version: "2.0.2"
base_url: "https://files.api.com"

methods:
  - name: upload_file
    method: POST
    path: /files/upload
    content_type: multipart/form-data
    auth: api_key
    input:
      file: binary
      folder_id: string
      filename: string
      metadata: object
      public: boolean
      expiry_days: number
    output:
      file_id: string
      filename: string
      url: string
      public_url: string
      size_bytes: number
      content_type: string
      upload_timestamp: timestamp
      expiry_date: timestamp
    errors:
      - code: 413
        message: "File too large"
      - code: 415
        message: "Unsupported file type"

  - name: get_file_info
    method: GET
    path: /files/:file_id
    input:
      file_id: string
    output:
      file_id: string
      filename: string
      url: string
      size_bytes: number
      content_type: string
      metadata: object
      created_at: timestamp
      download_count: number

  - name: list_files
    method: GET
    path: /files
    auth: api_key
    input:
      folder_id: string
      page: number
      limit: number
      file_type: string
      sort_by: string
      order: string
    output:
      files: "array[object]"
      pagination: object
      total_size_bytes: number
      folder_info: object

Example 4: Hybrid API/SDK - Messaging Service

service: MessagingService
version: "2.0.2"
supports_both: true
base_url: "https://msg.api.com"
sdk_class: MessagingClient

methods:
  - name: send_message
    # HTTP Implementation
    http:
      method: POST
      path: /messages
      auth: bearer_token
    # SDK Implementation  
    sdk:
      method: sendMessage
      execution: async
      requires_client: true
    input:
      recipient_id: string
      message_text: string
      message_type: string
      attachments: "array[object]"
      metadata: object
      scheduled_at: timestamp
    output:
      message_id: string
      status: string
      sent_at: timestamp
      delivery_estimate: timestamp
    errors:
      - code: 400
        message: "Invalid recipient"
      - code: 429
        message: "Rate limit exceeded"

  - name: get_message_status
    http:
      method: GET
      path: /messages/:message_id/status
    sdk:
      method: getMessageStatus
      execution: async
    input:
      message_id: string
    output:
      message_id: string
      status: string
      sent_at: timestamp
      delivered_at: timestamp
      read_at: timestamp
      retry_count: number

  - name: list_conversations
    http:
      method: GET
      path: /conversations
      auth: bearer_token
    sdk:
      method: listConversations
      execution: async
    input:
      user_id: string
      page: number
      limit: number
      status: string
      since: timestamp
    output:
      conversations: "array[object]"
      pagination: object
      unread_count: number

Example 5: Real-time Analytics API - Data Streaming

service: AnalyticsAPI
version: "2.0.2"
base_url: "https://analytics.api.com"

methods:
  - name: track_event
    method: POST
    path: /events
    auth: api_key
    input:
      event_name: string
      user_id: string
      session_id: string
      properties: object
      timestamp: timestamp
      context: object
    output:
      event_id: string
      tracked_at: timestamp
      status: string

  - name: get_realtime_stats
    method: GET
    path: /stats/realtime
    auth: api_key
    input:
      metric_names: "array[string]"
      time_range: string
      granularity: string
    output:
      metrics: "array[object]"
      time_range: object
      last_updated: timestamp
      refresh_interval: number

  - name: create_dashboard
    method: POST
    path: /dashboards
    auth: bearer_token
    input:
      name: string
      description: string
      widgets: "array[object]"
      filters: object
      sharing_settings: object
    output:
      dashboard_id: string
      name: string
      url: string
      created_at: timestamp
      widget_count: number
    errors:
      - code: 400
        message: "Invalid dashboard configuration"
      - code: 403
        message: "Insufficient permissions"

Example 6: Payment Processing - Complex Transaction Flow

service: PaymentProcessor
version: "2.0.2"
base_url: "https://payments.api.com"

methods:
  - name: create_payment_intent
    method: POST
    path: /payment-intents
    auth: secret_key
    input:
      amount: number
      currency: string
      customer_id: string
      payment_method_types: "array[string]"
      metadata: object
      return_url: string
      automatic_confirmation: boolean
    output:
      intent_id: string
      client_secret: string
      status: string
      amount: number
      currency: string
      created_at: timestamp
      expires_at: timestamp
    errors:
      - code: 400
        message: "Invalid payment parameters"
      - code: 402
        message: "Insufficient funds"

  - name: confirm_payment
    method: POST
    path: /payment-intents/:intent_id/confirm
    auth: secret_key
    input:
      intent_id: string
      payment_method_id: string
      save_payment_method: boolean
    output:
      intent_id: string
      status: string
      payment_method: object
      charges: "array[object]"
      confirmed_at: timestamp

  - name: get_payment_history
    method: GET
    path: /payments
    auth: secret_key
    input:
      customer_id: string
      status: string
      created_after: timestamp
      created_before: timestamp
      limit: number
      starting_after: string
    output:
      payments: "array[object]"
      has_more: boolean
      next_cursor: string
      total_count: number

Key Features Demonstrated

These examples showcase:

Authentication Patterns

Bearer tokens: auth: bearer_token
API keys: auth: api_key
Secret keys: auth: secret_key
Client authentication: requires_auth: true

Data Types & Structures

Primitives: string, number, boolean, timestamp
Collections: "array[string]", "array[object]"
Complex objects: nested metadata, configuration objects
Binary data: file uploads with binary type

HTTP Methods & Patterns

CRUD operations: GET, POST, PUT, DELETE
File uploads: multipart/form-data
Query parameters: pagination, filtering, sorting
Path parameters: :id placeholders

SDK Integration

Hybrid support: Both HTTP and SDK execution
Async operations: execution: async
Client requirements: requires_client: true
Method naming: camelCase SDK methods

Error Handling

HTTP status codes: 400, 401, 403, 409, 413, 415, 429
Descriptive messages: Clear error descriptions
Business logic errors: Domain-specific error types

Pagination & Streaming

Cursor-based: next_cursor, starting_after
Page-based: page, limit parameters
Real-time data: refresh intervals, live updates

Benefits

Fast Processing: Minimal overhead for AI agents
Easy Integration: Simple structure for quick adoption
Scalable: Perfect for microservice architectures
AI-Friendly: Optimized for LLM understanding and generation
Real-world Ready: Covers authentication, error handling, and complex workflows
Flexible: Supports both HTTP APIs and SDK methods

What is a Mini Wrekenfile?​

Key Characteristics​

Lightweight Structure​

Typical Structure​

Mini vs Full Wrekenfile​

Use Cases​

🤖 AI Agent Integration​

Development Workflow​

📡 Dynamic Loading​

Complete Examples​

Example 1: E-commerce API - Product Management​

Example 2: User Management SDK - Authentication Flow​

Example 3: File Storage API - Upload and Management​

Example 4: Hybrid API/SDK - Messaging Service​

Example 5: Real-time Analytics API - Data Streaming​

Example 6: Payment Processing - Complex Transaction Flow​

Key Features Demonstrated​

Authentication Patterns​

Data Types & Structures​

HTTP Methods & Patterns​

SDK Integration​

Error Handling​

Pagination & Streaming​

Benefits​