Iterating and maintaining APIs is crucial during product development. As products evolve with new features or adjustments, corresponding API updates or modifications become necessary, especially in fast-paced environments.
However, API iteration is not always straightforward. Managing APIs alongside product upgrades or modifications often presents challenges:
- How to effectively iterate and test APIs while ensuring the stability of existing APIs?
- How to manage APIs across multiple parallel development iterations, preventing interference?
To address these scenarios, Apidog introduces the "Sprint Branch" feature. This functionality provides a flexible way to manage APIs, allowing you to iterate, upgrade, and develop new features on independent branches without affecting the stability of online APIs in the main branch.
The Sprint Branch feature supports version control, parallel collaboration, and rapid merging. Each branch is an independent version, preventing interference, and changes within a branch can be quickly merged back into the main branch.
Understanding Sprint Branch Use Cases
The "Sprint Branch" feature allows you to create multiple development branches within a project to upgrade, iterate, and test APIs at different stages without impacting the main branch (i.e., the current stable version).
Oliver Kingsley
When to Consider Using Sprint Branch:
- Feature Development and Testing: Develop and test new features on a new Sprint branch without affecting the stable version on the main branch.
- Upgrades and Bug Fixes: Upgrade, update APIs, or fix bugs on a dedicated branch, merging them into the main branch after successful testing.
- Experimentation and Validation: Make experimental modifications to APIs, verifying their effectiveness before deciding whether to merge them into the main branch.
When Not to Use Sprint Branches:
- For minor API updates or simple bug fixes, it might be more convenient to operate directly on the main branch.
- If your business requires providing multiple API versions for external users, using the "API Versioning" feature is recommended to ensure stability and consistency for external users.
Below is a brief introduction to the "Sprint Branch" feature. For more detailed usage instructions, please refer to the Sprint Branch module in the help documentation. Before you begin, ensure that Apidog is updated to the latest version.
Creating an Sprint Branch
If your project role is "Admin" or "Editor," you can create a new Sprint branch to start iteration-related work by clicking the "New Sprint Branch" option in the "Sprint Branch" component at the top right corner of the directory tree.
Designing APIs in a Sprint Branch
Apidog's Sprint Branch feature only covers modified or newly added content during iteration. Therefore, the new Sprint branch is initially empty, and you need to select the content to be modified or added.
Imported resources, including APIs, API use cases, and data models, will have a clear association identifier with the main branch. Resources newly created within the Sprint branch will not have an association identifier.
During the API design process, you can also compare a specific Sprint branch resource associated with the main branch to view the differences between the resource and the main branch.
Testing APIs in a Sprint Branch
The "Tests" feature is also supported in Sprint branches. You can create new "New test scenarios" or import existing ones from the main branch.
In the directory tree, imported test scenarios will have clear association identifiers with resources in the main branch, similar to the resource identifiers in "APIs."
You can orchestrate test scenarios in a Sprint branch just like in the main branch. Since test scenarios may involve APIs from both the Sprint branch and the main branch, the system will use "branch icons" to distinguish which resources (Sprint branch or main branch) are used in each test step.
When you click to view the details of these steps, you can also see which branch their associated resources belong to.
Once the relevant APIs and test scenarios in the branch are designed and orchestrated, you can test them.
The system will use the corresponding data based on the resource source identified in the steps for automated testing. If a test step is identified as using resources from the Sprint branch, the test will use data from the Sprint branch; if it is identified as using resources from the main branch, the test will use data from the main branch.
Merging a Sprint Branch
After completing API development and successful deployment in the Sprint branch, you can merge these changes into the main branch. The merged content can be changed to some or all APIs.
The merge entry is located in the "Branch Component Dropdown Menu" at the top right corner of the directory tree. You can also see the "Merge to Main Branch" button below the directory tree in APIs.
Clicking the "Merge to main" button in APIs will open the merge overview popup. In the popup, you can view the modified or all resources between the current Sprint branch and the main branch. You can also choose how to adjust the status of the resources in the main branch after merging (e.g., "In Development," "In Testing," "Published," etc.).
Clicking on a resource in the directory tree will expand to show its detailed content, helping you decide whether to merge it. Different resource types will have different merging logic.
After the merge, a prompt will show the modified resources in the main branch.
Viewing and Reverting Merges in the Main Branch
In the "APIs" of the main branch, you can view the changes brought by recent merge operations by checking the resource history. You can also see which branch the merge came from.
You can view the specific modification content and compare it with other versions. This history function allows you to track change history and roll back content when needed.
Archiving, Restoring, and Deleting Branches
After merging a branch, you can access the Sprint branch management page through "Settings" -> "Sprint Branches." On the management page, you can view a list of all Sprint branches in the project and their statistics. You can also perform various operations on these branches, including archiving, restoring, and deleting iteration branches.
FAQs of Sprint Branches in Apidog
1 Are all types of APIs supported by the Sprint Branch feature?
Currently, only HTTP APIs are supported.
2. Who can create an iteration branch?
Project admins and editors.
3. Who can access an iteration branch?
Project admins, editors, and read-only members.
4. Who can merge changes from an iteration branch?
Project admins and editors.
5. Can an iteration branch be merged into another iteration branch?
Currently not supported. Only merging into the main branch is supported.
6. When working in an iteration branch, if the API in the main branch also changes, what will happen after merging?
After merging, changes in the iteration branch will overwrite changes made to the same API in the main branch. This means that any additions, deletions, or modifications to the API in the main branch will be replaced by the content in the iteration branch.
7. Is there a way to pull the latest updates from the main branch into an iteration branch?
This feature is under development and will be available soon.
8. If some resources are deleted in the iteration branch, what impact will it have on the main branch when merged?
If entire resources like APIs or data models are deleted, it means that these resources are no longer associated with the main branch. Therefore, the corresponding resources in the main branch will not be affected during merging, which is equivalent to no changes.
This is because a fundamental principle of Sprint branches is to only involve modifying and adding resources. Deletion operations need to be performed directly in the main branch, and the Sprint branch does not handle deletion operations.
If the API or data model resources in the Sprint branch are associated with the main branch, and you delete some of the resources (e.g., parameters, descriptions), the corresponding resources in the main branch will also be deleted after merging. This operation is equivalent to modifying the resources in the iteration branch.
9. If a new API with the same URL and parameters as an API in the main branch is created in the iteration branch, what will happen after merging?
Although the newly created API in the Sprint branch has the same URL and parameters as the API in the main branch, they are not associated by default. After merging, the main branch will add this new API that is exactly the same as the one in the Sprint branch, even if an API with the same URL and parameters already exists in the main branch.
Therefore, if you want to upgrade, test, or modify an existing API, please import the API from the main branch to ensure that they are associated. This way, if the API changes, the API in the main branch will also be updated synchronously after merging.
10. Can I revert to and restore the content of a previous sprint branch?
Yes.
If you need to view the content of a previous iteration for some reason, you can restore it from the archived state to the normal branch state (note the Sprint branch limit).
After restoration, you can access the branch again in the directory tree of APIs. The data in the branch before archiving will be automatically retained unchanged. If you want to restore the branch history content, you can directly use this branch to merge into the main branch again to complete the restoration.
For individual resources, it is recommended to use the "History" function directly in "APIs" for rollback and restoration.
11. Can I share the API documentation of a sprint branch with others?
For internal collaboration and sharing, you can share it with members who have joined the project through "Copy Collaboration Link." Currently, external sharing of API documentation is not supported.
Conclusion
Apidog's "Sprint Branch" feature optimizes the API design and testing process. By creating independent branches, teams can develop new features, fix bugs, and experiment without interfering with the main branch.
