Open APIs are a crucial tool for technical teams to share services and data with users. As businesses grow and technology evolves, APIs need to be updated regularly. These updates are typically designed to meet new market demands, improve existing features, add new functionality, or address security vulnerabilities.
As multiple versions of an API are often required to run simultaneously, teams need to manage these versions effectively. Some users may need the latest version to access new features, while others might prefer the stability and familiarity of older versions.
Oliver Kingsley
To meet these varying needs, teams often provide multiple API versions, such as the latest, stable, or long-term support versions. This helps ensure compatibility and stability for different user groups, minimizing the disruption caused by upgrades for users relying on older versions.
Apidog’s API Version feature is designed to make managing multiple versions easier. It allows teams to create, manage, and maintain different API versions, ensuring that each version operates independently and is clearly distinct from others.
Step-by-Step Guide to Create API Versions
Step 1: Creating an API Version
Once you enter your project, go to the branch switcher above the project folder and select API Versions to see all versions in the current project. Click on New API Version to create a new version. Name the version and select the initial content.
After saving, the system will automatically switch to the new version, allowing you to edit the resources for that version without affecting the original version.
Step 2: Publishing API Versions in Documentation
Once the API version is created, navigate to the "Share Docs -> Publish Doc Sites" section in the project.
Click on Edit to choose which API version to publish. You can specify the version’s source, display version numbers, set running environments, and configure the slug.
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 reorder the published versions. The first version in the list will be the default version, displayed to users accessing the project without specifying a version.
After completing these settings, click on Publish. The project will be marked as Published and users can access the API documentation via the documentation link, where they can switch between different versions.
Step 3: Quick Sharing of Endpoints in API Versions
In addition to publishing API versions, you can also share specific endpoints from any version of the API.
To do this, create a sharing link, select the API version, and choose the endpoints you want to share.
Once the sharing link is generated, users can view the selected endpoints for that version of the API.
Step 4: Deleting API Versions
To delete an API version, go to "Project Settings -> API Versions" in the main branch.
Once deleted, the public documentation will no longer include that version, and any sharing links associated with that version will become invalid. This ensures that users can no longer access content from the deleted version through those links.
FAQs of API Versioning
1. What is the difference between API versions and sprint branches?
API Versions: Mainly used for external publication. It’s best to create a new version when major changes that are incompatible with the old version are made. API versions include a full set of endpoints.
Sprint Branches: Used for internal team development. A new branch is created for each iteration, and it is merged into the main branch once completed. Sprint branches typically only contain new or modified endpoints.
2. Does the API version feature support all types of projects?
Currently, the feature only supports HTTP projects.
3. Who can create and modify API versions?
Project administrators and project editors can create and modify API versions.
4. Who can publish or delete API versions?
Only project administrators can publish or delete API versions.
5. Will changes to one API version affect another?
No. Each API version operates independently, so changes to resources in one version won’t impact other versions.
6. Are there plans to support more features, such as multilingual support?
Yes, we are actively working on features such as multilingual support and cross-branch/version pulls. These will be added in future versions to improve the management of API documentation.
7. What about enhancements for sprint branches?
There are ongoing upgrades to sprint branch features, including the ability to copy resources from other branches, pick resources from other branches, branch merge reviews, and branch locking. These enhancements will be available in upcoming updates.
Conclusion
Apidog’s API versioning feature makes it easy for teams to create, manage, and maintain multiple versions of their APIs. This ensures that older versions remain stable while new features are introduced. Whether you’re managing a single API or multiple versions for different user groups, Apidog streamlines the process, ensuring compatibility and minimizing disruption for users.
Ashley Innocent
