Apidog Tutorial: Managing API Versioning in Apidog

Open APIs are a key means for technical teams to provide services and data to external users. As business develops and technology evolves, APIs require regular version iterations. These iterations typically aim to meet market demands, optimize existing functionalities, add new features, or fix vulnerabilities.

With multiple versions coexisting, teams need to ensure that each version caters to different user needs. Some users might require the latest API version to access the newest features, while others may rely on the stability of older versions.

In practice, teams may need to provide multiple versions of the API to external users, such as the latest version, stable version, or long-term support version. This approach ensures compatibility and stability for different user groups, minimizing the impact of upgrades on older API users.

Based on such scenarios, Apidog offers a practical "API Version" feature. This allows teams to create, manage, and maintain different API versions easily, ensuring that each version operates independently and is clearly distinguished from others.

button

Using the API Version Feature in Apidog

Step 1: Creating an API Version

After entering your project, click on the branch switcher above the project directory and select "Version Content" to view all API versions in the current project. Click "New API Version," name it, and choose the initial content.

After saving, the system will automatically switch to the new version, allowing you to edit resources within this version independently without affecting the original version.

Step 2: Publishing API Versions in Documentation

Once an API version is created, you can go to the "Share Docs -> Publishing Settings" page in the project to select the API version you want to publish.

After setting the publication options, the selected API version will be displayed at the project's public address, making it accessible to external users.

Click the "Edit" button to choose the API version for publication. You can set the source of the version, display version numbers, running environments, and Slug.

💡

The Slug serves as a unique identifier for a specific API version that follows the public access address. For instance, in the URL https://example.Apidog.cn/2-0-0, 2-0-0 is the Slug, allowing external users to directly access that specific version of the API. This ensures that each API version has a unique and clear access path.

You can also adjust the order of published versions. The version listed first will become the default version, which users will see when they access the project address without specifying a version.

After completing the settings, click "Publish," and the entire project's status will change to "Publish" External users can then access the documentation through Apidog’s project address to view and switch between different API versions.

In addition to publicizing API versions, you can also quickly share specific interfaces from any API version.

When creating a sharing link, select the API version and the range of interfaces you wish to share.

After generating the sharing link, external users can view the interfaces you specified in that version of the API.

Step 4: Deleting API Versions

You can delete an already created API version from the "Project Settings -> API Versions" in the main branch.

After deletion, the publicly published documentation will no longer include that version, and any associated sharing links will become invalid, preventing users from accessing the deleted version's content through those links.

FAQs of API Versioning

What is the difference between API versions and sprint branches?

API Versions: Mainly used for external publication. It is recommended to create a new version when major changes occur that are incompatible with the old version. API versions contain a complete set of interfaces.

Sprint Branches: Primarily used for in-team development iterations. A branch is created for each iteration and then merged into the main branch after completion. Sprint branches usually contain only the new and modified interfaces from the current iteration.

Does the API version feature support all types of interfaces?

Currently, the feature only supports HTTP interfaces.

Who can create and modify API versions?

Project administrators and project editors can create and modify API versions.

Who can publish or delete API versions?

Only project administrators can publish or delete API versions.

Will changes to associated resources affect the API version?

No. Resources within each API version are independent.

Are there plans to support more features, such as multilingual support?

Yes, we are actively developing features like multilingual support and cross-branch/version pulls. These will be rolled out in future versions to further enhance the management efficiency of API documentation and meet more user needs.

What about enhancements for sprint branches?

Upgrades to the sprint branch capabilities are in progress, with plans to support features such as copying resources from other branches, picking resources from other branches, branch merge reviews, and branch locking in the upcoming updates.

Conclusion

With the API version feature provided by Apidog, teams can efficiently create and manage multiple API versions, ensuring stability for older versions while introducing new features.