API Version Control

API7 Enterprise offers robust version control to publish and manage API changes at the service level. You can publish your latest API configurations to various gateway groups. Unique service version numbers represent consistent business logic. It is also straightforward and reliable to roll back an API to a historical version.

In API7 Enterprise, APIs are organized and managed by services. All APIs within the same service version share the same version number when being published to gateway groups.

API Version Control Principles

When making changes to APIs, you should use proper version control strategies, which helps avoid breaking existing API consumers. Here are some key principles for managing API versions effectively.

Use Reasonable Version Numbers

• Major version increments (v1, v2) are used only when necessary breaking changes are required.
• Minor version increments (v1.1) are preferred for backward compatibility.
• Bug-fixing version increments (v1.1.1) should be harmless to the API consumers.
• Do not reuse deprecate version numbers.

Sync Rather Than Publish to Production Directly

Publishing a service will generate new versions every time. Every version should be fully tested in the test environment before going to the production environment, and should leave no chance for someone to change its configuration.

Typical Version Control Work Flow

1. Add two gateway groups for the test and the production environments.

2. Publish APIs to the Test Group with service version 1.0.0.

3. Validate APIs in the test environment.

4. Update API configurations in the service template.

5. Publish the bug fix to the Test Group again with version 1.0.1.

6. Synchronize APIs to the Production Group with service version 1.0.1.

   Note that service runtime configurations may vary from different gateway groups, but they do not affect the version number.

   info

   For example:

   • The API URL in the test environment is https://api7-test.ai/v1/pet, while the endpoint address is 127.0.0.1:80.
   • The API URL in the production environment is https://api7.ai/petstore/pet, while the endpoint address is 192.168.0.1:80.

7. For a new sprint, edit the service template to add more routes.

8. Publish APIs to the Test Group, with service version 1.1.0.

9. Validate APIs in the test environment and emergency happens.

10. Rollback the service version to 1.0.0 for recovery.