Skip to main content

Multi-Version Swagger Management

One of Nidra's strengths is the ability to work with multiple versions of the same API simultaneously, making it perfect for API version migrations and backwards compatibility testing.

Why Multiple Versions?​

Managing multiple API versions is essential when:

  • Supporting legacy clients during migration
  • Testing backwards compatibility
  • Developing new versions while maintaining old ones
  • Comparing behavior across versions
  • Coordinating with teams on different versions

Strategy 1: Separate Collections​

The simplest approach is to maintain each version in its own collection:

Collections/
├── MyAPI v1/
│   ├── Users
│   ├── Posts
│   └── Comments
├── MyAPI v2/
│   ├── Users
│   ├── Posts
│   └── Comments
└── MyAPI v3 (Beta)/
    ├── Users
    └── Posts

Pros​

  • Clear separation
  • Easy to manage
  • No confusion about which version

Cons​

  • Duplication of similar requests
  • Harder to compare versions side-by-side

Strategy 2: Version-Specific Environments​

Use a single collection with version-specific environments:

Collection: MyAPI (All Versions)

Environments:

EnvironmentbaseUrlversion
v1-devhttps://api-dev.example.com/v11.0
v1-prodhttps://api.example.com/v11.0
v2-devhttps://api-dev.example.com/v22.0
v2-prodhttps://api.example.com/v22.0

Benefits​

  • Single collection to maintain
  • Easy version switching
  • Shared request structure
  • Efficient for similar APIs

Suitable For​

  • APIs with minor version differences
  • Path-based versioning (/v1/, /v2/)
  • Header-based versioning

Strategy 3: Hybrid Approach​

Combine both strategies:

  • Separate collections for major versions (v1, v2, v3)
  • Environments for deployment stages (dev, staging, prod)

This works well when major versions have significant differences but minor versions are similar.

Importing Multiple Versions​

Initial Import​

  1. Import the first version as usual
  2. Name it clearly: MyAPI v1
  3. Set up v1 environments

Adding New Versions​

  1. Import the new version specification
  2. Choose "Create new collection" (not update)
  3. Name it: MyAPI v2
  4. Set up v2 environments

Keeping Versions Updated​

When a specification changes:

  1. Import the updated spec
  2. Select "Update existing collection"
  3. Choose the correct version collection
  4. Review changes
  5. Test affected endpoints

Cross-Version Testing​

Test the same workflow across versions using Conduits:

Approach 1: Duplicate Conduits​

  1. Create a conduit for v1
  2. Duplicate it for v2
  3. Update any version-specific differences
  4. Run both with their respective environments

Approach 2: Parameterized Conduits​

Create conduits that work across versions:

  • Use environment variables for version-specific values
  • Switch environments to test different versions
  • Compare results

Version Comparison Workflow​

To compare behavior between versions:

  1. Set up identical requests in both version collections
  2. Use the same input data (copy request bodies)
  3. Run requests against both versions
  4. Compare responses:
    • Status codes
    • Response structure
    • Data values
    • Performance

Example: Testing User Creation​

v1 Request:

POST {{baseUrl}}/users
{
  "name": "John Doe",
  "email": "john@example.com"
}

v2 Request:

POST {{baseUrl}}/users
{
  "fullName": "John Doe",
  "email": "john@example.com",
  "preferences": {}
}

Note the field name change (name → fullName) and new required field.

Handling Breaking Changes​

When a new version introduces breaking changes:

  1. Document the changes: Note what's different
  2. Update conduits: Modify test flows for new structure
  3. Maintain backward compatibility tests: Keep v1 tests running
  4. Create migration guides: Help team members transition

Version-Specific Variables​

Use variables to handle version differences:

v1 environment:
  userNameField: "name"

v2 environment:
  userNameField: "fullName"

Then in requests:

{
  "{{userNameField}}": "John Doe"
}

Best Practices​

  • Use consistent naming: Make version numbers obvious
  • Tag versions clearly: Use labels or tags in collection names
  • Document differences: Keep notes on what changed between versions
  • Automate regression tests: Use conduits to test all versions regularly
  • Plan deprecation: Know when to stop supporting old versions
  • Communicate with stakeholders: Keep team informed of version status

Example: Complete Multi-Version Setup​

Collections​

  • Payment API v1 (stable, legacy)
  • Payment API v2 (current production)
  • Payment API v3 (beta testing)

Environments​

  • v1-prod, v1-staging
  • v2-prod, v2-staging, v2-dev
  • v3-dev (beta only)

Conduits​

  • Payment Flow v1 (regression tests)
  • Payment Flow v2 (current tests)
  • Payment Flow v3 (experimental)

Next Steps​