Managing API Versions

APIs change. You might add a new parameter, deprecate an old endpoint, or completely restructure the response format. How do you handle this without breaking your documentation for existing users?

Apidog's Versioning feature allows you to maintain multiple versions of your documentation (e.g., v1.0, v2.0) simultaneously.

When to Version?

Breaking Changes: If you remove fields or change authentication, you must version.

Major Features: A v2.0 overhaul often warrants a fresh documentation set.

Minor Updates: For small non-breaking changes (adding a field), you usually just update the current version rather than creating a new one.

Creating a New Version

In Apidog, a Version is essentially a snapshot of your API resources.

Go to Project Settings > Versions.

Create a new version (e.g., v2.0).

You can choose to copy all endpoints from v1.0 as a starting point.

Now, you have two isolated workspaces. Changes in v2.0 won't affect v1.0 designs.

See details API Versions in Apidog

Publishing Multiple Versions

Once you have multiple versions designed, you need to expose them to the user.

Go to Share Docs > Publish > Release.

You will see a list of versions.

Add the versions you want to display (v1.0, v2.0).

Set the Slug for each (e.g., /v1, /v2).

Arrange the order. The top one is usually the Default.

User Experience

On your published docs site, a Version Selector dropdown will appear in the top-left corner (next to the project title).

Users can switch between v1.0 and v2.0.

The URL will change accordingly (e.g., docs.example.com/v1/...).

Key Takeaways

Versioning Strategy: Version your docs when introducing breaking changes to ensure backward compatibility for existing users.

Snapshot Versions: A version in Apidog is a snapshot of your API resources, allowing you to maintain v1.0 while designing v2.0.

Release Management: Publish multiple versions simultaneously and let users switch between them via a dropdown selector.

User Experience: Clear versioning signals maturity and stability, giving developers confidence to build on your platform.

This ensures that even as you innovate, you never leave your legacy users behind.

You've mastered the art of documenting your API. Now, let's wrap up this chapter with a Chapter Summary.

Managing API Versions

When to Version?#

Creating a New Version#

Publishing Multiple Versions#

User Experience#

Key Takeaways#

When to Version?

Creating a New Version

Publishing Multiple Versions

User Experience

Key Takeaways