Some students may think that the interface in the background has anything to do with our big front-end development? Think about it, when you encounter some unreasonable interface design, do you feel awkward when developing – you need to write a lot of dirty code for the stupid interface? Even, the page developed in this way will have a poor experience? We are not saying that the back-end interface is unreasonably required to be packaged according to the front-end business, but that for the better development of the project and for users to have a better experience, there should be room for discussion. Some poor designs should be rejected.
This article uses frontend to refer to Android, iOS, and the Web.
This article is not to teach you to tear up (hurry up and clear the relationship).
global
Global refers to the unified specification of all interfaces.
request header
HTTP headers should be used to place generic parameters, such as:
APPID (Android/iOS/H5)
APPVER (version number)
APP-BUILD-NUM (build minor version number)
TOKEN
NETWORK (network environment)
LANGUAGE (language)
and many more
The front-end is submitted to the back-end using POSTkey pairs, which can use the RawJSONformat.
Content-TypeSet to application/x-www-form-urlencodedor application/json.
Global Response Format
The response format should be unified, which is convenient for the front-end to do unified processing, especially the data fields, which should be unified in a map.
| name | type | Detailed Description |
| status_no | INT | status code |
| status_msg | STRING | status information |
| data | MAP | response content |
| time | INT | response timestamp |
status code
A unified status code (status_code) should be defined globally instead of defining each interface individually.
The specific rules can be defined by yourself, for example, 0 is correct, and negative numbers are wrong.
Common error status codes are
common exception
The token is invalid, you need to log in again
Repeat login
Need to improve personal information
To log in with a third-party account, you need to bind an official account
Invalid request headers (version number, APPID, etc.)
Data decryption error
The zone segments used can be divided according to the type of error, eg the landing series uses the -1000 to -1999 zone.
After this definition, the front-end can perform global unified processing, such as repeated login, the user will be kicked out.
error message
In addition to special error messages such as repeated login, invalid token status codes, as well as no network, no data, for general exceptions, the background should return error messages.
Unified data field
The data field should be uniformly placed in a map, which stores specific response information.
Scheme
A unified scheme (Deeplink) is defined globally to facilitate front-end jumping.
The front end only needs to define its own unique Deeplink and register it (scheme and host).
The specific use of REST style (such as markzhai://article/XXX) or ordinary urlencode (such as markzhai://article/?id=XXX&redirect_url=XXX) can be defined according to your own needs.
One concern with using the REST style is that the scheme itself may not be resource-based, but based on type, behavior, etc., so urlencode may be more general, but correspondingly Deeplink-based resource indexing will expect you to be stateless REST-style.
return or status code
Should I use a postback or a status code? For example, for a like message, should a status_code be returned, and 0 means the like is successful, or should the current like status be returned?
In fact, these two have almost no impact on the performance of the background, because only the final result of the modified field is obtained. But for the front end, there is a difference – the need to maintain state.
Take an example:
A and B are two users, B follows A, and A does not follow B.
When A looks at B’s homepage, it shows that the relationship is not followed . At this time, A clicks to follow. If no information is returned, then we can only refresh the relationship to Followed , and there is not enough information to refresh it to Follow each other . Otherwise, the front-end needs to do disgusting logic (the back-end needs to pass B to follow A at the beginning of the user relationship), switch according to the original relationship, and brush back to the original state when it fails.
Some experienced backends will use callbacks on this interface because they know the difference.
Modules vs Pages
In the background interface design, it is divided into pages and modules.
According to the interface of the page, make a front-end request for a page only once, and return all the required information at one time; according to the interface of the module, define your own business modules such as users, feeds, tags, search, etc. coupling.
From the perspective of the back-end, of course, it is better to use modules (as long as the division is fine enough). If there is any change in the requirements, let the front-end change the combination of interfaces by itself, so that you can sit back and relax. But from the front-end point of view, the combination of interfaces involves the relationship between asynchrony. Although a responsive programming framework such as RxJava makes asynchrony much simpler, it is still hoped that it can be avoided. More seriously, multiple interface requests will make The front-end experience is worse, and the impact of parallel interfaces is slightly smaller, while some interfaces with pre-post relationships are more troublesome. One request after another will make users wait for a long time. Even with parallel interfaces, sometimes page rendering still requires all interface data to be returned before proceeding.
However, if the backend is set according to the page, there is actually a performance loss in the backend, and a page interface is needed to call the interfaces of each module separately, and then combine them.
How to choose? The author believes that under the premise of sufficient server performance, the backend should try to reduce the number of page requests, especially serial requests with dependencies. On the other hand, on some pages with less impact, the front-end can perform interface combination by itself (for example, the user display of the user’s home page is shown above, and the feed list of the user is shown below).
In addition, if you have a good designer, then he should implement that a place should only be based on one thing, and should not be piecing together messy things.
Pagination information
In modern front-end interactions, page numbers are rarely displayed, so many back-end list page interfaces do not carry pagination information, and instead allow the client to maintain the requested page numbers.
So, is there really no need for paging information in the interface? Not necessarily.
Why do you need pagination information
The page size (pageSize) may change (whether it is the front-end own configuration or the background modification), if only the client maintains the page number, then the next request for the next page will go wrong unless the client brings its own last page size.
If the client does not know the current page number and the total number of pages, it cannot judge whether there should be more pull-up loading or no data at the bottom after the request, so it must be requested again, according to whether the list is returned and whether the data is empty or not.
In addition, returning the page number from the backend also avoids the possibility of errors in the client’s modification of the page number.
But for the backend, the acquisition of this information means greater consumption of computing and I/O resources.
compromise
As a compromise, you can let the backend return a has_morefield , which can avoid the last unnecessary request (especially when the data is not enough to display a full page), and the experience will be much better. Although this still cannot avoid the problem of page size change.
configure
Some backends like to let the frontend write restriction logic, such as keyword restriction for search and various filtering logic.
Let’s not mention the flexibility of writing these logics to the front end (the client side is different from the web page, so it can’t be so convenient to send the version, even if it is a web page, don’t you need to test if you change the code and send the version? If there is a problem, do you memorize it?). Can the front-end input really be trusted? Not to mention that the code may not be written rigorously enough to cause the input to skip the check, the user can also root, jailbreak, and even decompile the client or directly simulate the request.
So a good configuration check should have two
The back-end sends configuration fields, and the front-end checks the fields accordingly. The advantage is to reduce the pressure in the background, the disadvantage is that there is no guarantee of security.
The back-end receives the request and checks and filters it by itself. If there is an error, it returns an error message to the front-end for display.
Needless to say, the latter is better.
Also, let’s talk flexibility. Today, it may be limited to 3 words, and tomorrow’s product demand may be 4 words. Now the product/operation will not be changed, will it really not be changed at that time?
empty field
Some empty fields, if not, the server should return an empty default field, such as “” for String, 0 for int, {} for Object, and [] for Array, so as to reduce the error caused by the front-end verification that some verifications are missed. Case.
—- 由三帅泥阿布补充
I personally think that this does not have much traffic loss, and it does avoid many possible exceptions, which is a good opinion. Of course, just as the back-end should not trust the input of the front-end, the front-end cannot trust the completeness of the back-end data, and still needs to be verified tragically.
lesson
Don’t believe what will be refactored in the future. The interface says so now, and he will tell you later that it cannot be compatible with the old version, so this is the only way to do it (or even come up with two sets of rules to make you compatible at the same time).
Not that the back end is the boss. Everyone’s goal is to do a good job in the project, and now the front-end is usually more stressed than the back-end (the front-end is dizzy, and the back-end is online shopping), so on the premise that it will not greatly affect the performance It should meet the reasonable needs of the front end. Experience comes first. (Be tough, the boss should support you, and even go to tear it up in person, the big deal is to find the CTO)
Frequent modifications of the interface should be fed back upwards, and if the test data does not meet the requirements, it should be submitted in time. We don’t do the blame game.
Flexible and flexible. When making various demands, think about it, will this place change? Even if it doesn’t change now, will it not change in the future? For example, should the entrance in the drawer be configurable? Ask more and be as flexible as possible.
Summarize
This article talks about many common back-end interface design issues. Help everyone to have friendly discussions (tear and force) in the face of some unreasonable interface designs, so that the project can do better. You are welcome to add other points in the comments or by email ( [email protected] ), and I will mark the source.
