App back-end API design "Go"

Blogs: 44037011

The interaction between the app and the backend is typically implemented via the backend API. API design, estimated that many just enter the app back end of the small partners will have no clue, do not know how to get started. Below based on their 3 years of app backend experience, summed up the next several API design principles, to small partners reference.

1. What is an API?

This question has already been answered in the previously published article "7.app and app backend communication", which is repeated here.


I believe that we have used the bank teller machine (ATM) to check the balance, transfer, withdrawals and other operations.


When the teller machine withdrawals, we enter the amount to be withdrawn, the money will come out every other time, if there is any problem can not be withdrawn (for example, more than the withdrawal amount limit), the screen will also show the wrong information.


Throughout the process, we just enter the amount and get the results (the withdrawals are successful or unsuccessful), and as for how the teller machine is handled inside, we don't need to bother.


Teller machine This method of shielding the internal processing is very convenient for our use.


The same, in the backend, also only provides a series of functions for the app to use, this series of features in the form of API.


API Definitions: APIs (application Programming Interface, application programming interfaces) are pre-defined functions designed to provide applications and developers the ability to access a set of routines based on a piece of software or hardware without having to access the source code, Or understand the details of the internal working mechanism.


When the app calls the API, only the following 3 points need to be clarified:


1. What does this API do (in the case of teller machines, the withdrawal function, or the balance, or the transfer)


2. Know what to enter (in the case of teller machines, withdrawals are to be entered into money)


3. Know what the result is (in the case of a teller machine, the withdrawal is a success or failure)


As for how the API is handled internally, the app doesn't need to be ignored.


As you can see from here, the API minimizes the complexity of the app backend, greatly improving the development efficiency of the app front-end.

2.8 Points of API design

(1) RESTful design principles


RESTful style: restfu design principle, which was put forward by Roy Felding (in his "web-based software Architecture" thesis in the fifth chapter). The core principle of rest is to split your API into logical resources. These resources are manipulated via HTTP (GET, post,put,delete).


In the actual development process, it is found that programmers because of the habit of web-side, API operations are usually only two ways "POST" "GET". You can look at the microblog API example "Statuses/destroy", which is obviously the delete operation of the API is submitted by post. Not exactly the style of restful style.


The simplest application of this design principle is to design an API based on object rather than a page. At the very beginning, what data is needed on one page of the app, and what data is returned by the API. As a result, as the app's UI continues to change, the data needs to be constantly changed, the API is continually modified, and when the API changes affect the previous version, you can only write a new API version, and finally make the API a lot of v2,v3 such a sign, nightmare!


Later in the site reconstruction process, based on object to design the API, but according to object design, there is another problem, a large object may contain a lot of small object, is an API return all small object, or divided into multiple API return? Think about the business and technology, bandwidth, and so on.


(2) Naming the API


Look at the API name to know what this API is doing. In the entrepreneurial team, generally only one or two people in charge of the backstage, when you are responsible for dozens of or even hundreds of APIs, you know can not "look at the name of the API" is what kind of pain.


API naming, I am quite fond of Twitter's naming style, such as deleting the microblog API "Statuses/destroy", the first is the object, the second is the action of the object is deleted


(3) Security of the API


This will be discussed in more detail in the article "How to ensure the security of app communication" in the future.


(4) API return data


App Client language Java and object-c are strongly typed languages, so how to deal with null values is particularly important, unreasonable design can easily cause the app to flash back.


From the background point of view, the data returned in the API, the correct value and the type of the null value must be the same, for example, the User name field is "Realname": "XXX", if the user name is empty, you should return "Realname": "". If the return value is an array, the empty data returns an empty array, and the null value is absolutely forbidden.


For the client, a global function must be used to process the return data of all the APIs, and a mechanism is required: for a client to need data, if the API is missing, the client automatically complements and gives the default value. This mechanism greatly reduces the app's flash-back in our practice.


At the same time, when designing a database, a reasonable design must be that all fields have default values and should not allow null values. Null is an infinite problem in a large number of languages and databases. For this database design principle, I did not understand before, now after a year of API design, finally understand.


If the client is PHP, there is a problem, PHP arrays and dictionaries are array, but in Java and object-c is not the same, this problem must be noted.


(5) Processing of pictures


In different versions of the app, a variety of different sizes of mobile phones, the same picture display may not be the same size, if you need to return the original image each time, and then processing on the client, it is a huge waste of network resources. And if the background processing good pictures to return, it is a challenge, how to effectively save and crop a variety of image size it


For example, the first avatar only needs to return the size of the 60*60, later in the new version needs to return to 70*70, and a new version, need to return to 80*80, each time to add a new size, how to record on the database. This problem at the beginning of the API did not consider, and later had to use an extreme method, did not add new image size, in the database to add a new field, save and create a new image size, the results of the last database's Avatar field has "Avatar", "avatar_60_60", " Avatar_70_70 "," avatar_80_80 ", this extremely abusive design.


Finally, we used this strategy for the picture:


(1) The client locally caches the picture, only if there is no appropriate picture, to go to the server fetch.


(2) When the client needs a certain size picture, the client tells the server the size of the picture, the server is dynamically generated and cached.


For example, if the client needs the size of the 80*80 of the picture (Http://www.baidu.com/img/bdlogo.gif), then the path of the picture is prefixed with the width and height of the parameter (similar to the CDN mechanism) Http://www.baidu.com/img/bdlogo.gif? W=80&H=80, the server generates 80*80 dimensions and returns.


Using the image processing mechanism, as long as there is a field in the database to save the original picture, the other size is the client to tell the server dynamic generation. In the future no matter what size of the picture, the database does not need to record, the database only the original image on the line.


Note that now the file cloud storage services (such as seven bull, and the cloud) are provided with the zoom function of this file, and can speed up the upload and download speed of the file, greatly enhance the user experience of the app, highly recommended to use.


(6) The prompt information returned


In the most scientific case, the server returns only the information code, and the specific text prompt is determined by the client.


If the text information is returned by the server, the minimum is to distinguish 2 kinds of information: Prompt the user's information, prompting the client programmer's information. The difference between the two:


1. Prompt the user information is to let the customer know, prompt the client programmer's information does not need to let the customer know.


2. Prompt the user's information text is friendly, the customer does not need the professional foundation to know is what, prompts the client programmer the information is very specialized, for example tells the client to pass down which parameter? Which parameter has a problem and so on.


(7) Online API test documentation


Our website's API online testing documentation is used both as an online API document and as an on-line test tool that is extremely easy to communicate and test. Every time a client programmer feels that something is wrong with an API, we are talking about it on this online tool. The client programmer likes this thing most.


This API online test document was built using the Swagger-ui. The Swagger-ui is simple and easy to glance. It can be pure and broken based on the Html+javascript implementation, as long as a little integration can become a convenient API online testing tools. The development of TDD (test-driven) principles has been advocated in the design architecture of the project, and Swagger-ui is a great help in this regard.


Here is an example of an API in an API document built with Swagger-ui, which shows how the entire API is presented, and the parameters are very clear and unambiguous.


When the "test" is pressed, the API is called by post, and the results are as follows:


All return results, at a glance, cool!!!


The data returned by the API is returned in JSON format. In JSON format, the most traffic-saving, and almost every computer language supports JSON format. With XML, too much traffic, and redundant data, not suitable for the mobile side.


In the "app backend" QQ Group, there is an app founder using this API online test document after praise, praise although the initial construction takes a while, but greatly improve the efficiency of the front and back of the app work. After a small partner asked the relevant questions, he strongly recommended this swagger-ui.


(8) When the app starts, call an initialization API to get the necessary information


Through this initialization API, get the necessary information, for example, the latest app version. Users are prompted to update when they find that the version of the local app is below the latest app version. Of course, this prompt version of the update feature is available in many third-party SDKs.

3. How to handle version upgrade of API

When the app has made a big revision, there may be a problem, found that the current API is not enough, consider the upgrade of the API, and in order to be compatible with the published app, the original API must be retained. In order to avoid invoking different versions of the API in the same app, the API version is generally upgraded, for example: "Test.com/v1/statuses/destroy" and "Test.com/v2/statuses/destroy".


There are 2 points to note When upgrading the API version:


1. The controller of the V2 version of the API must inherit the V1 version of the Controller,v2 API to rewrite only the APIs that need to be changed.

2. The online API test document details The return content, has been compared to facilitate the debugging of the client staff.

App back-end API design "Go"