In my last post on Database and Cache synchronization, I received a comment from a reader asking me to talk about version control during API development. This is a good topic to talk about, as with any Internet product, as the requirements improve, you will encounter the same problem, I myself have been troubled by this problem. So today I try to make a summary, listing the API version control schemes I have encountered in different projects in the past, for everyone to make a reference, I hope to be helpful to friends.


API version control mode


Let’s start by talking about three modes of API versioning:



1. Do not set the version mode

This means that only one version is provided for each API. To modify the API, all users must use the latest API, and any modification of the API will affect all users.


2.API version mode

Multiple versions of an API with the same name can be created, and the API caller selects the corresponding API version based on his own requirements. The coexistence of the new version with the old version means that users of the old version will not be affected by the new version update.

3. Compatibility version mode

Each API has only one version, and the API must be compatible with the functions of previous apis. All version users call the same API, with built-in code to ensure compatibility.


From a practical point of view, mode 1 will be used only rarely, and mode 2 or 3 will be used mostly.


Implementation of API versioning



For the three version control modes mentioned above, let’s talk about how to implement each of them:


None Version mode Optional execution scheme



  1. The new function is directly modified on the old API, forcing the caller client (iOS/Android/H5) to upgrade. The user experience will be affected, but there are also certain technical difficulties, and the application scenarios are limited.

  2. Change the API name, new functions use the new API name, new version of the client to call the new API name, for example:

http://jiagouzhan.com/api/user/login

http://jiagouzhan.com/api/user/newLogin


Optional implementations of the API version mode



1. Add the version number to the URI. The URI directly marks the version that is used.

http://jiagouzhan.com/api/user/list

http://jiagouzhan.com/api/v2/user/list

2. Parameter with version number, that is, a version parameter is added after each API request to indicate which version is requested.

http://jiagouzhan.com/api/user/list?Version=2


Optional execution scheme of compatibility version mode



Version-based improvements that “hide” versions from the API.


  1. The version is specified through the HTTP header

When processing AN API request, the server determines the API-version set by the API caller in the request header, and then executes different logical processing branches, as shown below, to achieve version compatibility.


GET http://jiagouzhan.com/api/user/list

Host: jiagouzhan.com

Cache-Control: no-cache

Referer: http://download.google.com/

The user-agent: Mozilla / 4.04 [en] (small subsidiary; I; Nav)

Range:bytes=554554-

api-version: v1


2. Use the client token for control

When the client interacts with the server, there will always be a token field. We choose to “play” on the token. The server implements a token processor for mapping the token to the version.


http://jiagouzhan.com/api/user/list?token=5782b5e0512c7d47345d10af413b3d28

— — — — — > server token processing — — — — — – > determine internal version of the request API — — — — — — — — — — – > execute specific API > returns the result


There are two obvious benefits to doing this:


1. To some extent, it prevents many invalid requests. If HTTPS is used to transfer information, it will be more secure and prevent external attackers from using API requests to attack the server.

2. The server can flexibly configure the interface. As long as the client takes the default token parameter with each request, the client can get what the client wants.


Now that I’ve finished describing the API version control scheme, the discerning mind knows which one I recommend. 🙂 however, the solution is not absolutely good or bad, the key is whether it is suitable for the scene. If you have a better plan, welcome to leave a message.


Scan the QR code or manually search wechat public account [architecture stack] : ForestNotes

Welcome to reprint, bring the following QR code