One of the most common questions I receive in API design is how the API version control. Although not all are exactly the same API, but I found the API version control, some of the patterns and practices applicable to most teams. I have collected these contents, will provide some advice on the following version control strategy, the strategy will help the majority of API providers, whether they are deployed inward API, or external API.
API version really that important to you?
API is the link established between you and the API user. Under normal circumstances, the bond between you will not easily broken. URI pattern includes a link payload structure, field, and parameter names, expected behavior, and other content. The greatest benefit of this approach is obvious: API does not change the user's understanding of the application can ensure sustained and effective.
However, permanent change is unrealistic. Sometimes because the business changes, you may need to carry out major changes to the API. When this happens, the best way is that you will not do anything to ensure that API will lead the user to fix the code.
Breaking with uninterrupted change
Non-destructive change often like "additive", usually adding new fields or nested resources to the resource statement, and either add new endpoints, such as PUT or PATCH. API user from the beginning to build client code should be able to adapt to these non-destructive changes.
Groundbreaking changes include:
1. Name field or resource path, usually after release to unify the API naming conventions.
2. Change the payload structure, generally adapt to the following:
a. rename or delete fields
b. change the field from a single value-to-many relationship (such as moving from one email account to address a list of email addresses for this account).
c. Modify the API's URL, return inconsistent results led to the situation.
In short, once you release the API open to the public, you have to keep it available and will not affect users. If you are experiencing more than one item, you need the API version control, to prevent damage to the existing API users.
Defined API version policy
Any API evolving needs API version control strategy. Your API API version can be adapted according to the user's expectations and switch to a different version becomes different. I usually recommend the following API version control strategy as part of the overall management system API.
1. If you are in an early test version of the API in order to obtain consumer feedback, create your API may properly expect change to occur. During this stage, you will keep this version for some time, because your API design may also change. As a consumer, API is unstable, so they should expect to change is likely to occur.
2. Once published, your API should be treated as contract, if there is no new version, you can not be replaced.
3. ongoing changes can cause problems with the minor version, the client will automatically migrate to the latest version, without any negative side effects.
4. groundbreaking change means that customers will have to migrate to this new version, because it contains one or more major changes. You have to establish an appropriate schedule regular communication with the API user and to ensure that they can easily migrate to the new version. But in some cases, this may not be achieved immediately, so your team will be asked to temporarily support the previous version of the API.
When must implement the API versioning
Once the need for a new version of the API, we need to know how to handle it. API versioning realize there are three common methods.
1. Resource Version Control
This version is the Accept header part of the HTTP request, e.g., Accept: application / vnd.github.v3 + json sent to the GET / customers. This takes into account a number of the preferred form of version control, because the version of the resource needs while maintaining the same URI. If no Accept header provided some API will choose as the default version of the latest version.
2.URI version control
This version is part of the URI, as a prefix or suffix, e.g., / v1 / customers or / customers / v1. Although not as good as content-based URI version control version control so precise, but it is often the most common, as it applies to not support custom headers tools. The disadvantage is the resource URI change with each new version, some people think that this runs counter to the intent of the URI has never changed.
3. Host Name Version Control
This version is part of the URI instead of the host name, for example, v2.api.myapp.com/customers. when…
Note : No matter which option you choose, API version should contain only major number. It does not require small number (i.e., / v1 / customers, not /v1.1/customers).
Implement version control tools
Use tools and techniques can be implemented API versioning process fundamentally. API editor with excellent technical teams on the market will be able to generate more API version and switch in a shorter period of time, so as to continuously improve the design decisions.
Combined with tools for version control is an important part of most of the development process. API design is also a version control tools that can, in fact, the global API services that already exist in some excellent Web API design tools.
Now, as EOLINKER, RAML, Swagger, provides excellent editing tools to support their language. EOLINKER uses a version marked contrast and focus tips, you can clearly switched contrast. RAML, Swagger uses a version switch, convenience may be slightly inferior to that. But only the former is to support the Chinese, the latter two only supports the English language. These API editors can easily implement API version control, making it easier to switch running version in a shorter period of time.
Attach EOLINKER's official website: www.eolinker.com
Attach Swagger's official website: swagger.io/
Attach RAML's official website: raml.org/
Final thoughts
Remember, API is linked with your consumers hub. Breaking the old connection, you need the new version. Selection strategy, planning, and communicate the plan and API users, this is the ultimate goal of version control.
参考资料：James Higginbotham，When and How Do You Version Your API?
Original Address: dzone.com/articles/wh...