Inter-system interface design

The last two years have been and banks, public security, insurance, civil affairs and other third-party interface, write the interface document not less than 30, the original interface document is flawed, changed and changed, lost a lot of people, also criticized, complained, accused many times, over time, understand one of the most important reason, collaborative decision interface . When the two sides talk about interfaces, technology is not the most important, to take into account the two sides of technology, cost, duration and many other factors. But there are still many technical aspects of the experience, happened last week to participate in the Wen Yu Teacher's performance design of the outside training, inside the teacher talked about the interface design, just back together to tidy up the experience of interface design. This paper summarizes the interface design of the system from 3 aspects: interface definition, interface implementation, and other considerations.

First, the interface definition

interface is a standard for the interaction of data between the two parties (which may be systems, modules, services, etc.), custom interface to make the other side without doubt, the interface to consider the factors must be comprehensive, in general, the main consideration of 3 steps:

Interactive mechanism : such as synchronous request/reply mode, asynchronous request/Reply mode, session mode, broadcast notification mode, event subscription mode, reliable message transmission mode, file transfer, etc.

interface End : WebService, Scoket, transaction middleware, message middleware, file mode, shared database, etc.

interface Format : This is based on the selected technology, the actual situation to define.

Take our (industry-specific inconvenience) and the bank interface as an example (unlike every regional bank, take 1 for example)

Interactive mechanism: Asynchronous request/Response mode, we have to check the request when the bank interface, the request information sent past, the bank after the check and control, call our interface, the results of the search control feedback to us. After the call fails, there will be a retry and retry every 30 minutes.

Interface technology: WebService interface, Java Development, XML format message, data using 3DES encryption.

Interface Definition: Specific field description, XML format, and so on.

With these instructions, in the other side to get the interface document, no accident (such as the other party completely do not know the technology, can not understand) the other side can understand the interface, but also to describe clearly, if not answer these questions, I am afraid there is a loophole.

This interface is still a lot of imperfect, many places have a better choice, or the previous said, collaborative decision interface, appropriate.

Second, the interface implementation

Interface definition is complete, the development process to consider is non-functional level, such as various constraints, such as our side of the volume of data, concurrency is large, need to consider the following situations:

1. High-performance, support highly concurrent, large capacity, fast speed;

2. Robustness to prevent the system from being unusable due to large amounts of data or a large resource footprint;

3. Can monitor, at any time to see the operation of the interface, to facilitate timely detection of errors and troubleshooting;

4. Scalable, two aspects, one is to support the expansion of new features, and the second is to support the expansion of new hardware when concurrency increases.

Consider these may cause the interface change, for example, we consider high performance, speed, because we also correspond to more than 30 banks, each bank about 1000 times a day query, a single call needs 3w, so changed to support batch, a single call up to 100 people, send and receive about 5s or so. At the same time from the original serial changed to a concurrent call, using a thread pool (threads can not be too many, may cause the bank interface concurrency is too large to cause a crash).

Sometimes the active interface may not be the same as the timed polling interface, such as the above our interface is active, need to do connection pool limit concurrency, lest the concurrency of more to the bank caused problems, and then other provinces changed to be done entirely by us to do the service, the bank call to retrieve the request information to query, Although there are a few minutes delay (according to the bank polling time decision), but the development of a lot of simple, considering the situation is also a lot less, the interface speed is much faster.

When considering monitoring, there are many open source monitoring components, such as the javamelody we use, that can monitor the number of executions of a class.

Consider extensible, extensible function, such as we use XML, JSON format message, or other custom format, there are certain rules, do not use the specific meaning of the parameters, once additions and deletions will affect the interface.

Third, the matters needing attention

1. Support batch, this must have, mainly for performance considerations, the subsequent data volume is large, and then modify the support batch will lead to the entire interface modification, so it must support batch.

2. Support partial unpacking, such as the best in the message to parse the message header can know the specific business or can find the logic of processing, to avoid all the resolution to know how to deal with, such as we and a company do interface (they make interface), there are more than 10 implementation classes, their file encryption, Must be decrypted after the whole to read to use which implementation class processing, file about 200M, each processing about 5s, 3s are selected with which implementation class, concurrency and its slow, later changed to the front 32 bytes marked which implementation class, later processing each packet 2s around, performance increased by more than 40%.

3. Security, the security control of the interface includes: Security evaluation, access control, intrusion detection, password authentication, security audit, anti-malicious code, encryption and other contents. According to the actual situation, some units require high, some do not matter, do not involve the Internet projects, encryption in order to prevent the administrator to see, and so on, the request is not high Base64 on the line, or 3DES, higher channel certification, and so on according to the specific situation.

4. Entity files, FTP and other ways to transfer the entity file is easier, we use WebService more, the general use of small files converted into text (BASE64), when the text transmission, the advantage is simple, the disadvantage of one is slow, two is the file is large or concurrent large, the memory may not be enough; We generally put on the FTP, and then passed to the other side of the FTP path, this configuration is more troublesome.

5. Log, this is the most important, each link of the interface to maintain a detailed log, you can set priority, after the online printing to a file or only to retain the important, because the site error can only be based on log analysis, in many cases the other side of the interface problem when the other party does not admit, or after the other side of the responsibility to throw You will find the most reliable is the log.

6. Monitoring, this is also too important, but we often ignore, many times the two sides of the joint test is no problem, often a line on the problem, not only the amount of data, concurrency, etc., at this time there is a monitoring page, you immediately will be confidence doubled.

7. Interface document writing, the general company has its own interface document template, of course, we also have, most of the templates are mainly defined a number of steps, such as background, function description, interaction mechanism, security ... I'll sort this out. When I discuss with various units, some of the documents described are not clear, mainly some format definitions, field descriptions and so on.

(1) field type, must unify the standard, such as date, time format, insufficient to fill 0, such as 2015-01-0112:01:02.

(2) The entity file, which is Base64 after passing a string, or another rule, or passing an address on an FTP, if it is an address, if it ends with a slash "/" and so on.

(3) Numerical value, the exact number after a few digits before and after the decimal point is not enough to fill 0.

(4) exception, preferably with error code, or other information, and error post-processing mechanism.

(5) How to check the required fields, whether the code values need to be verified, etc.

(6) The most important point, finished must give others to see, see if others can read, use words accurately, whether there are omissions and so on.

Above is just some general summary, suitable for some Web projects, and many other modes of the interface is not applicable, the points are not in-depth research, follow-up research and then add into it.

Inter-system interface design