Design API with product thinking (iii)-version control, not as simple as you think.

Design API with product thinking (iii)-version control, not as simple as you think. Preface

The recent restructuring of the project code within the company, including the API direction, encountered a lot of problems during the period, I could not help but think again.
-How is an elegant API designed?
-Does the API really decouple after the front-end separation?
-Continuous version iterations, API compatibility How do I do it?

PS. The API described here is for Web APIs only and provides App\web development use.

Years ago, our internal interface has entered a complete reconstruction phase, reference to the market on the major platform of the API and documentation, I also summed up a lot of experience. To share this with you, for the next one months, we will introduce to you the following aspects of an elegant API (at least I think it is very elegant) how to design.

1. RESTful is a scam (http://blog.csdn.net/yzzst/article/details/53775319)
2. Decoupling of data is the essence of back and forth separation (http://blog.csdn.net/yzzst/article/details/53844590)
3. Version control, not as simple as you Think (http://blog.csdn.net/yzzst/article/details/54755077)
4. Arbitrarily define the error code, are you still doing this?
5. Safe, you can only use HTTPS?

Ps. Play an advertisement, the company is now in the recruitment of various technical posts, Java, Android, front-end, etc., the treatment guarantee can let you rise 30%, interested friends can add Tao Brother's (No.: STCHOU_ZST), QR code in the end of the article.

What are the common practices in the industry today?

In the area of restful APIs, there are 3 ways to do versioning, the industry is currently more mainstream:

URI version Control

That is, in the URI directly tag which version is used, no version number URI default to use the latest version. As follows:

http://xianlinbox/api/customers/1234  http://xianlinbox/api/v3.0/customers/1234  

• Benefits:
  Directly in the URI can see the API version intuitively,
  You can view the results of each version of the API directly in the browser
• Harm:
  The version number breaks the rest's Hateoas (hypermedia as the engine of the application state) rule in the URI. There is no direct relationship between the version number and the resource.

URL parameter control

That is, after each request, add a version parameter that indicates which edition is requested. As follows:

http://server:port/api/customer/123?version=2  

This approach is actually a variant of the URI pattern, the good and bad are the same.

Mdedia Type Control

That is, using media type in the header of the HTTP request to mark the resource that the request wants to get, the same can not set or set the generic media type to represent the latest version of the API.

GET /customer/123 HTTP/1.1  Accept: application/vnd.xianlinbox.customer-v3+json  HTTP/1.1200 OK  Content-Type: application/vnd.xianlinbox.customer-v3+json  {"customer":    {"name":"Xianlinbox"}  }  

• Benefits:
  follows the design style of rest (Tencent is basically this style)
• Harm:
  The version is not intuitive and requires the client to be able to set the header to invoke the effect of viewing the API.

So many versions of the API version control, in fact, it seems that the difference is not very much, it is not very different. Choosing so much is not a good thing, which one should we choose?

Wait, what do we do with version control?

In the app version iteration, the requirements notconsistent, the API interface shampoo logic has changed, in order to be compatible with different versions of the app, you need to version control API.

Such as:

/getUserInfo （获取用户信息）接口

return information

{    nikeName : "诚壹小主",    sex : 0,    email : "[email protected]"}

Now the demand has changed, the information of this interface has changed, need to add an avatar field, display the user's avatar in the app.

{    nikeName : "诚壹小主",    sex : 0,    email : "[email protected]",    avatar : "http://www.test.com/pig.png"}

Just adding a avatar field does not affect the client parsing JSON. Difficulties are difficult in many cases, we do not want to add a field, but instead change the information returned by an existing field.

For example, it is necessary to change the content of sex from "0" to "female"

{    nikeName : "诚壹小主",    sex : "female",    email : "[email protected]"}

The mapped bean properties have changed and cannot continue using this interface, and must be upgraded. We can use any of the above three forms. Such as:

/v2/getUserInfo

The problem is solved, but new problems are introduced. Our notconsistent needs only modify such an interface. The contents of the other ports have not changed, and neither the path nor the version number need to be modified. As a result, the following problems occur after several iterations:

1. The version number of the client request is confusing, redundant

异步更新版本号：/getOrder/getAppList/getProductList/v2/getUserInfo      （与上面的是不是一套API，能不能混用，搞不清楚）同步更新版本号：/v2/getOrder         （没更新）/v2/getAppList       （没更新）/v2/getProductList   （没更新）/v2/getUserInfo      （更新了sex字段）

1. Old version of interface exposed, there is a security risk

遍历请求/v1/getUserInfo/v2/getUserInfo/v3/getUserInfo/v4/getUserInfo.............

1. Back-end Logic code compatibility redundancy

Api/common/controllers/usercontroller. PHPPostcontroller. PHPModels/user. PHPPost. PHPModules/v1/controllers/usercontroller. PHPPostcontroller. PHPModels/user. PHPPost. PHPV2/controllers/usercontroller. PHPPostcontroller. PHPModels/user. PHPPost. PHP

A lot of problems, let us think together, just a version of the number to judge, is not enough. The client is not allowed to choose which version of the API to use. the control of the API must be client-side transparent and server-led .

How to lead the different content of API?

How to dominate it? The server must know all the client's information, such as version number, device name, device size, channel number, positioning information and so on, can be done according to different versions of the app, different device apps, different areas of the app issued different content. (previously thought only to do statistical use)

In particular, let's look at the API requests for today's headlines:

POST http://is.snssdk.com/article/category/get_subscribed/v1/?iid=7692187251&device_id=25714927584 &ac=wifi&channel=xiaomi&aid=13&app_name=news_article&version_code=600&version_name= 6.0.0&device_platform=android&ab_version=100436%2c103308%2c101786%2c101533%2c103122%2c100193%2c97143% 2c103497%2c103545%2c103104%2c101558%2c102627%2c103524%2c94045%2c92439%2c103679%2c103557%2c103215%2c102771% 2c98046%2c101405%2c95564%2c103630%2c103435&ab_client=a1%2cc4%2ce1%2cf2%2cg2%2cf7&ab_feature=94563& Abflag=3&ssmix=a&device_type=mi+5&device_brand=xiaomi&language=zh&os_api=23&os_version =6.0.1&uuid=862155031730905&openudid=3037046a77716479&manifest_version_code=600&resolution= 1080*1920&dpi=480&update_version_code=6001&_rticket=1485485393465 HTTP/1.1accept-encoding:gzipuser-agent:dalvik/2.1.0 (Linux; U Android 6.0.1; MI 5 Miui/v8.1.3.0.maacndi) newsarticle/6.0.0 okhttp/3.4.1Cookies:_ba=ba0.2-20161220-51e32-adup8amwlxczaifa41lv, login_flag=c462a98391e078f9487d2fae9969466e, sid_tt= d934f60b0d1fd46efd4580d08ca19575; Sid_guard= "d934f60b0d1fd46efd4580d08ca19575|1484070881|2592000| thu\054 09-feb-2017 17:54:41 GMT "; Qh[360]=1; alert_coverage=68; _ga=ga1.2.1091613933.1472312132; install_id=7692187251; TTREQ=1$4426684A5AA688958281215CCF4D3922EAFAB5A1; sessionid=d934f60b0d1fd46efd4580d08ca19575X-ss-req-ticket:1485485396229Content-type:application/x-www-form-urlencodedContent-length:1250Host:is.snssdk.comConnection:keep-alivecity=%e5%8c%97%e4%ba%ac%e5%b8%82&latitude=39.984465&longitude=116.343119&loc_time=1471575017&categories=%5b%22__all__%22%2c%22news_finance%22%2c%22news_hot%22%2c%22news_local%22%2c%22video%22%2c%22news_society%22%2c%22question_and_answer%22%2c%22subscription%22%2c%22news_entertainment%22%2c%22%e7%BB%84%e5%9b%be%22%2c%22news_tech%22%2c%22news_car%22%2c%22news_sports%22%2c%22news_military%22%2c%22news_world%22%2c%22essay_joke%22%2c%22image_funny%22%2c%22IMAGE_PPMM%22%2c%22news_health%22%2c%22positive%22%2c%22jinritemai%22%2c%22hotsoon%22%5d&version=4222937564%7C12%7c1485184142&iid=7692187251&device_id=25714927584&ac=wifi&channel=xiaomi&aid= -&app_name=news_article&version_code= -&version_name=6.0.0&device_platform=android&ab_version=100436%2c103308%2c101786%2c101533%2c103122%2c100193%2c97143%2c103497%2c103545%2c103104%2c101558%2c102627%2c103524%2c94045%2c92439%2c103679%2c103557%2c103215%2c102771%2c98046%2c101405%2c95564%2c103630%2c103435&ab_client=a1%2CC4%2ce1%2CF2%2CG2%2CF7&ab_feature=94563&abflag=3&ssmix=a&device_type=mi%205&device_brand=xiaomi&language=zh&os_api= at&os_version=6.0.1&uuid=862155031730905&openudid=3037046A77716479&manifest_version_code= -&resolution= the*1920&dpi=480&update_version_code=6001&_rticket=1485485393465

In fact, the headline is very simple, the need to operate all the data in the API request to the back end, both to do statistical requirements and can be targeted to send different content, grayscale testing, personalized recommendations commonly used this routine.

Looking back at our demo before this article, we can re-outline our API structure, as shown in:

So, when do we change the version of the API?

In fact, grabbed a lot of home app package, found that the revision is relatively small. For us, it should be the protocol of the API has changed, the entire API architecture has changed, this large change and need to be compatible we will deploy more than one set of API to give the client call.

Written in the back, the recent Chinese New Year, the company's busy business, reconstruction mission is significant, the update blog is also slow. I hope you will forgive me.


@author zhoushengtao(周圣韬)
@since 2017年1月27日 12：39
@weixin stchou_zst
@blog http://blog.csdn.net/yzzst


Design API with product thinking (iii)-version control, not as simple as you think.