One: Why write API interface documents

The API interface document is an important tool for other collaborators to debug together during the development process. It is like an operation manual. If you are given an item, you may not know how to use it, but if there is an operation manual, you can let someone who just got the item People, quickly proceed to use items. In the same way, the API interface document is a manual for other writers to quickly understand, quickly use, and perform interface call operations.

Interface documents, you may hear a lot of jokes on the way to work, such as: programmers hate others not writing interface documents; programmers least like writing interface documents...

In fact, while contradictory, it also reflects the importance of interface documents.

Fortunately, I have received a lot of interface documents because I often connect with three-party systems. The _ forms in them are all kinds of strange, each has its own advantages, some are standard, and some are difficult to read. _

Two: common document forms

Common documents have the following forms

1. webServer document format

WebServer documents are generally used in shopping malls or financial systems. Generally, such documents include business implementation logic diagrams and Web service distribution descriptions (which define the interface of Web services, such as service names, provided methods, and method parameter information);
The request format is generally POST;
The data format is generally XML;

2. Swagger-UI style document

Such documents can realize online interface editing, automatically generate tokens to implement subsequent interface test calls, and are generally based on RESTFUL interface specifications.
This type of interface can visually see whether the interface is available.
Address: https://teevid.github.io/mwapi/index/

3.SDK documentation

As shown in the title, the other party encapsulates the interface operation into a specific SDK package, then the caller only needs to instantiate the SDK, and then can refer to the document to call the method. This method is simpler and the cost of docking is low, but the provider is required to provide the SDK of the corresponding language. This has a certain development pressure.

4. Online api documentation

For such APIs, you can refer to online documents such as Weifutong , Gaode Maps , Meituan API , Douyin API , etc. Such documents have the same basic format and are universal, and generally provide http/https requests for calls by various development languages.

5. API interface word document

This type of interface is generally used for privatization development to provide api documents, which will be explained below.
The document specifications provided by each company are different, some conform to the RESTFUL style, and some directly output the POST format interface uniformly.

Three: What should the API interface word document contain?

For non-standard interface documents, it is really a headache. For example, I once received an api document, a sign encryption algorithm, and the document was written in four steps. However, when I followed the steps to encrypt it, I found that I could not get it. The correct value, after repeated confirmations to no avail, I coordinated with the relevant developers of the other party to assist, however, a horrible thing happened, after we debugged together, the encryption steps were as high as 14 steps.
Needless to say whether there are any examples in the document, even if there are, the gods will not be able to communicate.

1. Change record

The change record is a good thing. When, who modified what content, first of all, it is convenient for other collaborators to understand which interfaces have been updated in this version. What supporting adjustments need to be made? Of course, when something goes wrong, the role of traceability is also very important.

2. Document purpose

What this document is used for, generally introduces the content of cooperation between privatization deployment developers and users.

3. Interface specification

This section generally introduces open interface specifications, such as: transmission method (http/https), submission method (interface specification, restful style or all post), data format, character encoding, signature algorithm, test environment address;

4. System parameters/public parameters

System parameters are parameters carried by each interface, describing the basic information of each interface, used for statistics or other purposes, generally placed in the header or url parameters;

parameter	illustrate
version	version number (version control)
time	Timestamp (anti-replay)
from	Source (interface from where to access, h5/applet)
sign	sign

5. Signature algorithm

This is a very important step. For a good signature algorithm document, the steps must be clear, and each step must be shown with an example. The final obtained sign can be verified.

6. Standardized business coding

Generally, according to the restful style, the return value includes code, message, and data; when the code is 200, the interface is correct, and the rest of the code values are all errors;
generally, the wrong return value code needs to be displayed in a table;

7. The specific interface must have parameters

7.1 Interface name

This need not be explained, a correct interface name is very important

7.2 Interface Introduction

What function does this interface use to achieve.

7.3 Interface request format

Based on the RESTFUL style, it is necessary to indicate the request format of the interface on each interface, POST, GET, PUT, DELETE;

7.4 Interface address

It is the api address of the interface

7.5 Interface Input Parameters

Explanation of input parameters, including field name, whether it is required, field attributes, and field descriptions;

7.6 Interface output/return value

Explanation of parameters, including field name, whether it is required, field attributes, and field descriptions;

7.7 Request Example

It is generally recommended to spell the domain name or test address together

7.8 Input parameter example

as follows

7.9 Parameter example