Service API version design and Practice

1 Preface

The following is the development process of the app store from millions of days to tens of millions of days . The app store client has gone through hundreds of version iterations, large and small , The server also completes the transformation from monomer to service cluster in architecture 、 Microservice upgrade .

Let's talk about the rapid development of business , Product iterations , The server is compatible with different versions of clients API Some experience and experience of the problems encountered . On the one hand, let the children's shoes in the team have a more thorough understanding of some existing design ideas , On the other hand, I also hope to arouse the resonance of some peers who encounter similar scenes , Provide solutions .

2 Common solutions

App store client iterations are very frequent , Release new APP At version time , It is bound to lead to multiple versions , In this way, the server will cause multiple different client requests . Force users to upgrade APP, It may lead to the loss of users , Therefore, it is necessary to adopt multi version coexistence . Here are some of the topics discussed in the industry SOA service API Version control method reference [1]. The actual development of the Central Plains is inseparable from the following three schemes .

Scheme 1 ：The Knot No version —— It's the platform API There will always be one version , All users must use the latest API, whatever API All the changes will affect all the users of the platform .（ Here's the picture 1）

Option two ：Point-to-Point—— Point to point , It's the platform API Version comes with version number , Users choose to use the corresponding API, Need to use new API characteristic , Users have to upgrade themselves .（ Here's the picture 2）

Option three ：Compatible Versioning—— Compatibility version control , and The Knot equally , There is only one version of the platform , But the latest version needs to be compatible with the previous version of API Behavior .（ Here's the picture 3）

Simple analysis ,The Knot Maintain only the latest version , For the server side, maintenance is simplified to a certain extent , However, service users are required to adapt the latest version in time , This approach is not applicable to user products , At present, the internal service is more applicable .Point-Point Provide independent services for different customer versions , With the increase of versions, the maintenance cost of development and operation and maintenance will increase , This is what we face in the back “ Agreement upgrade ” Used when .

Scheme 3 should be the most commonly used case , The server is backward compatible . The following cases mainly adopt this idea , There are many specific methods , Different strategies will be used in combination with specific business scenarios , This meeting is the focus of the next discussion .

3 Challenges and exploration of specific business scenarios

3.1 The Knot No version and Point-to-Point Application scenario of the pattern

The figure above is a microcosm of our app store iterative changes , When the business develops to a certain stage, it faces the following challenges :

1） In the early stage of business development , As a service provider , The server should not only support multiple versions of the app store client , At the same time, it serves the software side PC assistant ; 2） The product forms vary , The change and maintenance of server interface face the challenge of multi version client compatibility ;

3） Architecture logic , The server adopts the early traditional architecture , Development and maintenance costs are relatively high ; The protocol optimization and upgrading of the interaction between the server and the client ; And service splitting is imperative .

So the server protocol 、 Framework upgrading and public service splitting are the primary solutions . The transformation has gone through two processes :

• Stage 1 The new interface of the new version shall adopt the new interface JSON agreement ; Existing functional interfaces for compatibility processing , Distinguish according to the client version , Return the format and content of different protocols .
• Stage two As the business iterates , After all the interfaces that the new version store depends on have completed the protocol upgrade , In order to improve the stability of the service , The performance of the old protocol cannot be significantly improved , On the one hand, upgrade the back-end architecture and framework , Improve development efficiency and maintainability . Split and separate new projects at the same time , The implementation history project is only available for historical versions . We aim at high traffic and high concurrency 、 And basic service scenarios, such as home page 、 details 、 Download and split the independent service . At the same time, some public internal RPC service , For example, get application details 、 Filtering services, etc .

After modification , The server architecture is shown in the figure above .

1） thus Old-Service In the future, only corresponding maintenance work can be carried out , Corresponding Point-to-Point edition ;

2） Inside RPC Service because it only provides internal services , The server and client can be upgraded synchronously at any time , Just maintain the latest version , use The Knot Pattern . It should be noted here that the service upgrade should be kept downward compatible , You need to be very careful when expanding or modifying fields , Otherwise, it may cause exceptions called by the client when the service is upgraded ;

3.2 Compatible Versioning: Compatibility version control

Compatibility version control should be the most common version control method , Especially in C/S Architecture , Specific compatibility versions and different strategies are summarized as follows API edition 、 Client version number 、 Function parameter mark, etc .

Scene one : API Version number control

With the development of Internet , User experience requirements are also getting higher and higher , The product form will also change differently every year . In addition to avoiding aesthetic fatigue , We are also constantly exploring how to improve the screen effect 、 Click through rate and conversion . Take the app store home page list as an example .

The application list has experienced a single Apply double row -> Single row -> Single row + Interspersed with Layout . The content has also experienced different commercialization models 、 Evolution from manual scheduling to algorithm .

The internal logic of each version interface changes greatly , There are obvious differences . If it's just simple in service The layer judges and processes according to the version , This will cause the processing logic to become extremely complex , It may also affect lower versions . At the same time, the home page of the store is a very important business scenario , Considering the risk , For scenes like this , At the interface URL New version field on , Use different values for different versions , In the control layer, different processing logic according to different versions will be more reasonable , Simple and effective . There are also specific strategies, such as in URL Add interface version field on /{version}/index、 The request header carries version parameters, etc .

Scene two : Client version number control

Similar to the home page list , Interspersed with shops Banner It has also experienced multiple versions of iterations . As shown in the figure below . These interspersed styles appear in different versions , In the style layout , Support jump ability and other aspects. The support level of each version is different , Corresponding processing and adaptation are required when the interface returns 、 Filtering, etc .

In this kind of scenario, if the scheme of scenario 1 is adopted to upgrade the new interface, it can also be solved , But there will be a lot of duplicate code , Moreover, the new interface is for the transformation of the client interface 、 In particular, some interface paths will affect the statistics of big data buried points , There are also relatively high communication and maintenance costs .

In order to improve code reusability . Using client version number control is the preferred policy . But we need to pay attention , If you simply judge according to the client version number at the code level , There will be the following problems to consider :

1） There will be various judgments at the code level , Resulting in poor code readability , Is there a more elegant way ;

2） There is an objective situation . That is, the version number of the client is uncertain . Because the client adopts the train release mode Reference resources [2], Multi version parallel development , This causes the version number to change 、 Discontinuous version jumps occur from time to time , It also brings a lot of trouble to the server development .

How to think and solve these problems ？ In fact, some resources or product modules involved in different product forms appear in different iteration cycles , It can be considered that they have the attribute of version or time . From the programmer's point of view , Take the corresponding client version supported by a resource as a member attribute of the resource object . After each resource has this attribute , There are also corresponding logical behaviors to correspond to member methods --- Filter by attributes . This design endows resources with attributes and behavior , Resources have a unified 、 Flexible filtering capability , Instead of simply hard coding according to the version if-else Judge .

With a plan , It's easier to implement . Develop and allocate resources ID, And set the corresponding supported client version range . The filtering logic is unified to the resource object .

At the code level, the filtering logic can be encapsulated into a tool class （ Sample code ）, Filter the returned data in each business interface . A more elegant solution is to establish a unified resource upper class , Encapsulate resource filtering methods , The resource objects of all resource bits implement the upper class , The filtering ability is unified in the acquisition of resource logic .

Scene three : New function identification parameter

The app store business mainly provides users to discover and download new applications 、 Update your phone's installed apps . The store has incremental updates to reduce the volume of update packages , Therefore, it is also called provincial traffic update , Effectively enhance the user experience . In the early stage, we used the open source incremental algorithm , However, it is found that the algorithm takes a long time to synthesize and split packets on some machines , Even cause crash.

So the project team seeks a more efficient splitting algorithm . Similar to the scenario of function enhancement in these existing interfaces , In addition to providing new API Or simply extend it by judging the client version internally , Is there a better plan ？ Because in addition to the known disadvantages of these schemes , Need to think in the long run , For example, the algorithm mentioned earlier , Will there be any possibility of upgrading in the future , Will there be more enhancements to the download interface .

Think in combination with the above , Add... On the basis of the original interface Flag parameter Field , Indicates the capability supported by the client issuing the request . For further expansion , The field type is an integer value , It's not just simple boolean, Server through Bit operation completes judgment logic . The client also gets rid of the strong consistency between a function and the version , You don't have to record a version, you have some ability .

4 More thoughts on interface design

Finally, add some stepped pits and reflections . When the server provides an interface , You can't just focus on the implementation of the interface , More often, we need to pay attention to the user of the interface , The scenes they use 、 Call timing, etc . Otherwise, the development is troubleshooting interface problems 、 Maintenance will take several times longer than actual development .

1） Scene ： Specifically, what is scenario , Take the store client to help users detect whether the application version installed on the mobile phone is the latest service for example , There are different scenarios for detection timing , For example, the user starts 、 User switching wlan Environmental Science 、 Timing detection, etc . When fine analysis is needed , Which requests are valid , What causes centralized requests , At this time, if there is no scene distinction in the request , Then there will be no way to start the analysis . Therefore, when communicating with the client interface design , Please bring the scene factor . For interface design, refer to, for example /app/{scene}/upgrade, Define each scene name , Bring specific scenes on the path , In this way, the order of magnitude of requests from different online sources 、 Problem analysis will be of great benefit .

2） Authentication and service isolation ： In addition to the scenarios that need to be considered , The interface call shall be recorded, authenticated and service isolated during allocation . For example, some interface services of the store are not only provided to the client , At the same time, it will also be provided to mobile system application calls . at present vivo Hundreds of millions of stock users , Be very careful here , Improper control of call volume of system application , Concurrency is much larger than the store itself . First, evaluate and communicate with the service caller in the early stage 、 Design well , Avoid problems . Even when something goes wrong , There should also be a mechanism to quickly find problems 、 Be able to analyze the source of the problem , Reduce the loss caused by the problem .

So far, the above idea to solve the problem , It has a certain relationship with the specific business and background . With the continuous iteration and development of Technology , In mobile terminal APP Page dynamics , At present, the industry also has more efficient technical solutions , Like Google's Flutter、Weex etc. . These technologies can achieve flexible expansion , Multi terminal unification , Performance can also be close to native. It not only reduces the frequency of client version distribution , It also reduces the cost of server compatibility processing . At present, we vivo There are also teams using and practicing .

Technology is changing , There is no best plan , There is only the most appropriate solution . The development process not only meets the current implementation requirements , More consideration is given to the subsequent scalability and maintainability . Development cannot blindly pursue high-end technology , Technology ultimately serves the business , Stick to long-term principles , Efficiency first .

The following article is from vivo Internet technology