Skip to content

Versioning

Jump to bottom
Claude edited this page Oct 14, 2025 · 4 revisions

Versioning

API Dock supports versioning for both remote APIs and databases through subdirectory-based configuration.

Overview

Versioning allows you to:

  • Maintain multiple API versions simultaneously
  • Route requests to specific versions
  • Auto-route to latest version
  • Version database schemas independently

Configuration Structure

Versioned Remotes

Instead of a single remote.yaml file, create a directory with version files:

config/remotes/
├── my_api/
│   ├── 0.1.yaml
│   ├── 0.2.yaml
│   └── 1.0.yaml
└── another_api.yaml  # Unversioned (single file)

Versioned Databases

config/databases/
├── user_db/
│   ├── 0.1.yaml
│   ├── 0.2.yaml
│   └── 1.0.yaml
└── simple_db.yaml  # Unversioned

URL Structure

Accessing Versioned Endpoints

Remotes:

/{remote_name}/{version}/{path}

Databases:

/{database_name}/{version}/{route}

Examples

# Specific version
curl http://localhost:8000/my_api/0.1/users
curl http://localhost:8000/user_db/0.2/users/123

# Latest version (auto-selected)
curl http://localhost:8000/my_api/latest/users
curl http://localhost:8000/user_db/latest/users/123

# Unversioned (backward compatible)
curl http://localhost:8000/another_api/users
curl http://localhost:8000/simple_db/users

Version Sorting

API Dock automatically determines the "latest" version using smart sorting with a float-first strategy:

How It Works

  1. Try float parsing first: Attempt to parse all versions as floats
  2. If all parse successfully: Sort numerically (highest first)
  3. If any fail to parse: Fall back to string sorting (reverse alphabetical)

Numeric Versions (Float Parsing)

Versions: [0.1, 0.2, 1.0, 1.2, 2.0]
Latest: 2.0  # Correct numerical ordering

Float parsing ensures 1.2 > 1.0 > 0.2 > 0.1.

String Versions (Fallback)

Versions: [v1, v2, v10, v11]
Latest: v2  # String sort (reverse alphabetical)

Note: String sorting can have unexpected results (v2 > v11 alphabetically).

Mixed Versions (Float First)

Versions: [0.1, 0.2, v1, v2]
Latest: v2  # Can't parse "v1" as float, use string sort

When versions can't all be parsed as floats, the entire set uses string sorting.

Version Configuration Files

Remote Version (0.1.yaml)

name: my_api
description: My API - Version 0.1
url: http://localhost:5000

routes:
  - users
  - users/{{user_id}}

Remote Version (1.0.yaml)

name: my_api
description: My API - Version 1.0
url: http://localhost:5001  # Different backend

routes:
  - users
  - users/{{user_id}}
  - users/{{user_id}}/profile  # New in 1.0
  - posts
  - posts/{{post_id}}

Database Version (0.1.yaml)

name: user_db
description: User Database - Version 0.1

tables:
  users: s3://data/v01/users.parquet

routes:
  - route: users
    sql: SELECT * FROM [[users]]

Database Version (1.0.yaml)

name: user_db
description: User Database - Version 1.0

tables:
  users: s3://data/v10/users.parquet
  permissions: s3://data/v10/permissions.parquet  # New table

routes:
  - route: users
    sql: SELECT * FROM [[users]]

  - route: users/{{user_id}}/permissions  # New route
    sql: |
      SELECT p.*
      FROM [[permissions]] p
      WHERE p.user_id = {{user_id}}

Version Metadata

Access version information without a route:

# List available versions
curl http://localhost:8000/my_api
# Returns: {"remote": "my_api", "versions": ["1.0", "0.2", "0.1"], "latest": "1.0"}

# Get version config
curl http://localhost:8000/my_api/1.0
# Returns: {"name": "my_api", "description": "...", "url": "...", "routes": [...]}

Migration Strategies

Gradual Migration

Keep old and new versions running simultaneously:

# 0.1.yaml - Old schema
tables:
  users: s3://data/users_old.parquet

# 1.0.yaml - New schema
tables:
  users: s3://data/users_new.parquet

Clients can migrate at their own pace:

# Old clients
curl http://localhost:8000/user_db/0.1/users

# New clients
curl http://localhost:8000/user_db/1.0/users

Breaking Changes

Use versions for breaking API changes:

# 0.1.yaml - Original response format
routes:
  - route: users/{{user_id}}
    sql: SELECT user_id, name FROM [[users]] WHERE user_id = {{user_id}}

# 1.0.yaml - New response format with additional fields
routes:
  - route: users/{{user_id}}
    sql: |
      SELECT u.*, p.permissions
      FROM [[users]] u
      LEFT JOIN [[permissions]] p ON u.user_id = p.user_id
      WHERE u.user_id = {{user_id}}

Deprecation

Deprecate old versions by documentation:

# 0.1.yaml
name: my_api
description: "DEPRECATED: Use version 1.0. This version will be removed on 2025-12-31."
url: http://localhost:5000

Best Practices

  1. Semantic Versioning - Use meaningful version numbers (0.1, 1.0, 2.0)
  2. Document Changes - Update description in each version file
  3. Keep Old Versions - Don't remove old versions immediately
  4. Test All Versions - Ensure each version works independently
  5. Default to Latest - Use /latest/ for most recent features

Version-Specific Restrictions

Each version can have different route restrictions:

# 0.1.yaml - More restrictive
routes:
  - users
  - users/{{user_id}}

# 1.0.yaml - More permissive
routes:
  - users
  - users/{{user_id}}
  - users/{{user_id}}/permissions
  - users/{{user_id}}/settings
  - admin/dashboard

Testing

# Test all versions
curl http://localhost:8000/my_api/0.1/users
curl http://localhost:8000/my_api/0.2/users
curl http://localhost:8000/my_api/1.0/users

# Verify latest points to correct version
curl http://localhost:8000/my_api/latest/users
curl http://localhost:8000/my_api  # Check version list

Compatibility

  • Unversioned configs work - Backward compatible with single-file configs
  • Mixed setup supported - Some remotes versioned, others not
  • No code changes needed - Versioning is purely configuration-based

See Also

Clone this wiki locally