Back-end interface for front-end spit groove those things.

Today with another front-end developer pulled up the back-end interface of the skin (I am also the front-end staff), that the brother to the backend staff to provide a large view of the interface (I am commonplace), but he does have a reasonable point, so combined with my opinion, hope to provide the interface of the staff can pay more attention.

1. No documentation ...

For example, the new front-end personnel to a new company, when using the interface, ask this this do not know, ask that that do not know, to document No document, this is absolutely the front-end personnel most crazy thing, in the heart must be 1000 grass mud horse Pentium.

Why document?

1. The document is a guide that the current developer and even the back of the tray (behind developers) can clearly follow.

2. Even if it is simple, if you do not write the document, word-of-mouth will consume more work than writing the document.

3. Good memory is not as bad as writing, after a while, maybe even developers forget the purpose of the interface.

How is the document written?

1. Online documentation.

Online documentation is easy to update and viewable by others, such as the ability to write interface documents using swagger.

Ps:swagger is a normative and complete framework for generating, describing, invoking, and visualizing restful Web services.

2. Local documentation.

Local documents are generally used in Word documents, but are less easily propagated but can be viewed offline.

final~

Documentation is critical, whether it is an online document or a local document. Although it is troublesome to write a document, it is beneficial to the back-end people.

2. Incomplete documentation ...

Well, that is, if you have a document, the description of the interface in the document may not be complete, with each parameter being described in detail (range of values, type), request (GET, POST, PUT, DELETE), all states of the returned data, and so on. The most missing is the status of the returned data!

The normal return data structure ~

The company's data interface return structure is

{     0/1,     // represents the processing state (status) of this operation, generally simple success/unsuccessful, using 1/0 notation.      m: ' xxxx ',  // indicates the prompt message (message) for this action, and is typically used only to show the message when the operation failed.      R: [],  // indicates the return value of this operation (result)     count:x  // number of data bars returned }

This data structure seems to be fine, and there is no big problem, the problem is in the S field. There are many interfaces not only two states, the success of only one is not a problem, the problem is in the failure state, the failure may have a lot of circumstances, a simple s:0 can not explain the reason for failure (that is, there is a m hint information, but use this to differentiate very unreliable, because the hint may change), We do not always take m for display only.

Upgrade return Data Structure ~

The colleague suggested answering in the following way

{     0/1/2/3,     //  0 for normal, 1 is the wrong parameter, 2 is the user does not exist, 3 is the user does not have permission and so on     m: ' xxxx ',  // a hint message (message) that represents this action, and is typically used only to display the prompt message when the operation fails.      R: [],  // indicates the return value of this operation (result)     count:x  // number of data bars returned }

M, R, Count can remain unchanged, but s must contain all return states, representing all the business of the interface, and front-end developers can handle each case.

final~

The most important part of the document is the status of the return value, and I recommend that the above upgrade return a data structure so there is no ambiguity. Now that you have written the document, write the document well and write it clearly, which is also a good place for people to be selfish.

3. Interface parameters not verified ...

This front-end personnel is not very concerned, because the interface itself before the calibration will be done first, the back end of the parameter check is only a double guarantee. I have also done a period of time back end, also committed the error of not verifying parameters, the amount, because later did not do back end, also did not go to fix. But still remind the back-end personnel, good parameter check is the first step, do not lazy.

final~

The interface check is handled uniformly, and the backend is well considered.

4. No guarantee of interface atomicity ...

The atomicity of an interface is important, and sometimes an interface may do a few things, but not all of it can be done normally, which leads to the possibility of atomicity and the interface cannot be called accurately.

PS: atomicity. An atomic transaction is either fully executed or simply not executed. This means that each task in the unit of work must be executed correctly. If either task execution fails, the entire unit of work or transaction is terminated. Any changes that were made to the data previously will be revoked. If all tasks are executed successfully, the transaction is committed, that is, the modifications to the data will be permanent.

final~

Atomicity must be guaranteed, guaranteed, guaranteed!

5. Interface problems constantly ...

Front-end developers to adjust the interface, there may be a variety of problems, there are problems to understand, the program will not bug, but not too outrageous ah, back-end brothers. So I think I'm going to make a few things clear before giving the interface:

1. Verify the parameters.

2. If all the cases have been tested, please write unit tests if possible.

3. Whether the return data is accurate and clear, the response status code is normal.

4. Whether the document is complete or not.

Summarize

Back-end staff more considerate front-end personnel, in the case of problems, first check themselves, do not come up with the front end to dry up, if their problems are embarrassing.

This article for the original article, reproduced please retain the original source, convenient traceability, if there is the wrong place, thank you correct.

This address: http://www.cnblogs.com/lovesong/p/5533149.html

Back-end interface for front-end spit groove those things.