Software iteration is a problem that developers must face, and one issue that is easily overlooked these days is API version control. Not all users are keen on the latest version of software, and business is fluid. So when a new version is released to ensure backward compatibility, API version control is needed. Today we will discuss the common Restful API version control.
2. API Version Control
Restful API version control is closely related to the business, but currently many average level product managers do not consider this, without a smooth transition will easily cause business turbulence, affecting the brand image and user experience.
Master version consistency strategy
When business changes are destructive to previous clients and incompatible, we should release this business release as a major version (Major), or else release it as a minor version (Minor).
The client should verify the consistency of its own master version number (1 in the above diagram) with the server’s master version, and can ask the user to upgrade when it does not match. This kind of control is the simplest and most hardcore. But not all scenarios are suitable for this approach, sometimes we need to support multiple versions of the client in parallel.
Multi-version parallelism all require the client to carry the version identifier in the request, which is usually done in the following ways.
Marking the version in the URI
Fatty mostly uses this approach in tutorials of previous articles, adding
/api/v1 before all URIs, where
1 is the version number, which is iterable.
Marking versions in Host
You can also specify the version by Host, such as
https://v2.myapi.com point to different versions respectively, this kind of use is also more currently.
Declare the version in the Header
The above two will bring the version number explosion, so try to use it in major revision. To ensure the consistency of the API, you can also set the version number in the request header, e.g.
We identify the API version we expect to request by adding
Api-Version to the Header.
3. How to route
Routing in the case of multiple versions is a problem, which needs to be talked about in conjunction with the way the application is deployed. If it is a single application with multiple versions, we need to write filters and interceptors for routing, here the URI approach is an exception, the minimum granularity of the version control of the URI is already the interface. This approach is generally used for small and medium-sized projects more.
If you are running
v1 version on server A and
v2 version on server B, you need to resort to gateways, proxies for routing, no matter where your version number is declared. As an example, the request header carries the version number and is routed by Nginx.
Host, URI can be similarly routed for distribution.
By here you can also consider how a simple canary distribution can be done.