How to write a good interface document

Preface:

Watched recently written a lot of very good interface documentation, in understanding the business gives a lot of help, solve the problems of data, most of the time for some consultation at the same time, the follow-up work of the individual, also need to be open to the public interface to a third party to call, at that time a good specification document can solve many problems.

Article purpose:

1. Personal to write interface documents for some data collation.
2. Learn how to write a document that people will want to read.
3. Hopefully, this article will help you deal with the awkward situation when you have to write your own interface documentation.

Directory:

There are two versions. Each version has its own characteristics and needs to be used in different application scenarios

1. Simple version
2. Complex version

Simple version

Core: If your case can be used directly by copying, it is a good document

Since want simple, that grasp the core: how simple how to, how to save time how to

If you don’t know how to write, make your case as detailed as possible.

Development time is precious, and interface docking is often written quickly under tight deadlines, and for fragmented time workers, a simple and intuitive document may be more desirable.

In addition, the final form of the interface document is best to be PDF. In the past, when the interface document is written in Word, various problems such as style may occur in different versions

Best way: Word -> PDF

Simple version of directory format

• Interface specification
• Sample request
• Request Parameters
• In response to the sample
• Response Parameters

Case Template 1:

Interface description:

Interface functions:

This interface is used to obtain the token information of a user.

Interface request address:

https: xxx/xxx/xxxx
Copy the code

Request header:

Request header	Request content	instructions
Authorization	Basic secretKey	Access token
Content-Type	application/json	Request way

Request mode: POST

Parameter type: JSON

Example request:

Most of them are JSON in a custom format

[{"id":"20201219"."name":"21.59"."age":"ftp_1002". }, {"id":"20201219"."name":"21.59"."age":"ftp_1002". },]Copy the code

Request Parameters

The field name	Fields that	The field type	If required
Field 1	Describes the function of field 1	varchar(50)	is
Field 2	Describes the function of field 2	int	is
Field 3	Describes the function of field 3	decimal	is

In response to the sample

Successful response code:

{
    "code: "200","message":"The request is successful","data": return data in custom format}Copy the code

Failure response code:

{
    "code: "200","message":"The request is successful","data": return data in custom format}Copy the code

Response Parameters

Interface return code	Interface Return description
200	successful
400	Request parameter exception
401	Authorization failure
500	A system exception

Case Template 2:

The following template is useful for a single interface, but it is also intuitive for some simple interfaces

The core is that a table contains all the information, which is more effective for some very large number of interfaces or similar interface parameters. This can make the content more compact, and you will not forget the trouble of the previous page when you look at the next page. Of course, the disadvantage is also obvious, there will be the situation of text accumulation.

Markdown’s tables are not very intuitive when storing Json data, so use Word instead

The interface name	UserUpdateService
Interface Request Address	www.baidu.com
Functional specifications	The UserUpdateService interface is used to change the account of the application system
Request parameters	Parameter names	English description
	RequestId	A random ID generated by the platform for each call and returned by the application for each response. This ID is a String
	uid	Primary key UID of the account returned to the application system when a third-party application system account is created.Will the field
	loginName/ fullName	Attributes of the account field to be modified
Response parameters	Parameter names	English description
	RequestId	The ID of the request sent by the platform each time the interface is invoked. The field is String
	resultCode	The result code of the interface call processing,0 indicates normal processingOther values are defined by the application system. The field type is String.Will the field.
	message	Interface call processing information. The type of the field is String
Example request:	{” token “, “”,” treeCode “, “EXECUTIVE”, “code”, “”}	Markdown presentation is not very nice, suggest Word
The return value	{ “xxxx”: “xxxxxx”, “resultCode”: “0”, “message”: “success” }	Markdown presentation is not very nice, suggest Word

Case template 3:

The following may not be very intuitive, but reference to a lot of documentation found that there seem to be a lot of similar, also can refer to.

Request address: http://www.baidu.com

l Property list

The property name	Chinese name	Value types	Value must be	describe
token	The token	String	is
treeCode	Mechanism tree coding	String	is	If the value is left blank, it indicates the ROOT organization. By default, enter ROOT.
code	Organization code	String	is
start_date	Start date	Date		The start date of the contract or project
name	Name of institution	String	is
end_date	End date	Date		The end date of the contract or project
user_num	Number of personnel stationed	Int
supplier_name	Supplier name	String
type	Body type	String	is	Project Torg, AdministrativeOrg
orgUpCode	Upper body code	String	is
parentId	The parent organization code	String	is
isDisabled	Whether to disable	Boolean		false

L Response attribute list

The property name	Chinese name	Value types	Value must be	describe
code	Return code	String	is
message	Return information	String	is	If the value is left blank, it indicates the ROOT organization. By default, enter ROOT.
data	Returns the content	String	is

l JSON Data Example支那

[http://xxxxxxxx/xxx/xxx]Request parameters:"{" token", "", / / mandatory" treeCode ", "EXECUTIVE", / / will fill in the "code", ", "/ / will fill in the" entity ", "{"code":"2222", // Required" start_date":"","name":"The field names", // Required"end_date ":"","user_num":"","supplier_name":"", "type "," ", "// Specify the type"orgUpCode":"11111", // Required"parentId":"1111111", // Mandatory isDisabled: "false" // Whether to disable}"Response: login JSON - Example data {"success": true."data": {
     "treeId": "ROOT"."parentId": 112034."name": "3333",},"errorCode": null."errorName": null."errorMessage": null."errorException": {
  "name": null."message": null."trace": null}}Copy the code

So far, a simple interface document is pretty much all there is to it. Here’s a more complex (and extensive) approach

Complex version

Because different companies have different requirements for document format, here is only a list of a few documents I have seen, not necessarily universal, not necessarily perfect, but I hope the content can have a certain reference value.

The complex version has a bit more content. Please be patient or bookmark (=v=)

Complex version of directory format

+ cover + interface file name + interface version number, copyright information + + document title | | create time print time + | | | | storage directory in the file name owners action item: Copyright statement (point 1) + + version history \ | the \ | version number date \ | describe \ | to \ | modifier + \ | v1.0.0 \ | | \ \ | | XXX XXX XXX + + directory structure is clear, organized and can quickly locate the information you need to (later) + Specific contents of the document + Purpose + Preparation for interconnection + Test commissioning + going online + Protocol + specification + packet specification + Request packet specification + Response packet Specification + Interface description + Packet specification + Request packet + response packet + Common packet header + interface code description + Service interface + Query interface + encryption and decryption specification + principle + token information + encryption specification + decryption specification + service interface + specific interface 1: + Description + specification code (looking up the table) + Usage mode + Request field + Response field + Case + specific interface 2.... . + Appendix + References 1 + References 2 + Others.....Copy the code

Case study:

Cover:

The cover is still quite important, after all, it is the first content of the document when you open it. Below, using Ali’s document as a reference, you can see that the cover is generally as follows:

• The name of the company
• The document name
• The version number

Document Information:

The document information mainly records the generation date and the specific creation and printing date of the document.

The document name	content
The title	A handsome document
Creation date	20xx-xx-xx
Date printing	20xx-xx-xx
The file name	Full name of the document
Storage directory	File location
The owner of the	Xyz company
The author	Zhang SAN

Copyright Notice: copyright is extremely important in this day and age.

It is owned by XXXX and shall not be borrowed, transferred or published by three parties

Version history:

Version history is very important. Every change needs to be recorded in detail, so as to ensure that the document is clean and effective. At the same time, it is convenient to review the document for the reviser

The version number	The date of	An overview of the	reviser
1.0.0	20xx-xx-xx	create	Zhang SAN
1.0.1	20xx-xx-xx	Modify the first section of the document	Li si
1.0.2	20xx-xx-xx	Updated the error description in section 4 of the document	Cathy

Directory:

A good document must have a good directory, as long as according to a certain specification and format written out of the document, generally look very comfortable. Still use Ali’s development manual for reference

The specific contents of the document

This part of the play of the free space is relatively large, different businesses, different companies, different needs of different people can write thousands of formats of documents, so here is a sample for reference use. Practical value varies from person to person.

In order not to make the whole directory tree too long, there is no title =-=

Writing Purpose:

What problems need to be solved, why this document is needed, and what is the reference value of this document?

Preparations for connection:

What content the interface can provide, what content the interface needs to provide to the interface, and other information, such as system application ID, system unique identifier, to provide to the interface. Provide a key to the peer, and so on

1. Test coordination: assign test keys, account and password of test environment, and other information

2. Go online: What do you need to do after going online, for example, replace the production URL, the account password of the production environment, and the key to the production key

Use protocol + specification:

It can be the algorithm and communication protocol used in the docking, the description of terms or other instructions related to the business, and the requirements of the docking. There is a large space for free design.

Message specification:

Packet specification is the core part of interface interconnection, because most of the time is spent in interface parameter debugging and request debugging. So the message specification is very important. For details, refer to the interface description in the simple version or in the directory format

+ Request packet: mainly the Body of the request and the header content of the request, which are generally in Json format and required UTF8 encoding + Response packet: the format and content of the return, which is also the part to be negotiated + Common packet header: Generally, the parameters that need to be reused can be used as common packet headers. However, not all common packet headers are mandatory. Optional parameters + interface code description: Describes the precautions for an interface and the field parameters that need to be paid attention to. Generally, it represents the service return result. For example, unified 2000 is used as the success response code of the packet. All other codes are designed based on the corresponding interface code table. + query interface: how can it be regarded as a successful query, such as a refund interface may be accepted, rejected or processed, and so on query interface information descriptionCopy the code

Encryption and decryption specifications:

It is also the most important part, is also more time to spend, need a lot of debugging to get through the interface, there are several points

• Rules: The interface has some simple rules, such as asymmetric encryption, digital signature, and timestamp validity. You can set the rules according to the rules of the interface

• Token information: It is an important part to describe how the token is generated, which is usually completed by the communication between the two parties. It is better to explain with cases and code

• Encryption specification: describes the encryption process of interface data. For more important content information, it is better to explain with cases and codes

• Decryption specification: it explains how to decrypt the interface. For example, it needs to get the paired public key from the server to decrypt, and then it uses the signature + parameter to verify the signature is correct and so on.

Encryption and decryption specification reference:

General encryption, generally do the following form can basically block most of the attack:

1. Sort the map lexicographically by key and add ittimetampValue check Check time
2. Concatenate the parameters into some special formkey=value&key=valueWith a timestamp or some other information at the end, such as an application Id, to verify identity
3. This string is encrypted with AES and then BASE64 encoding to generate an encoding string
4. The BASE64 encoding is MD5 encrypted, and when encrypted, you get a fixed-length MD5 string
5. The signature is generated by md5 encryption based on the MD5 string + the string above, and the signature is basically unique

Business interface

Basic can copy simple interface template here, since the interface description description of each person is different, here are some basically involves points, in addition, this one step to the auxiliary use cases, and because case interface can help readers more quickly learn and understand, pay attention to this part of content: the practicality is greater than theoretical

Specific interface:

1. instructions
2. Specification code (table lookup)
3. use
4. Request field
5. The response field
6. case

Appendix:

Perhaps this part and the manual basically nobody read, so I don’t do too much explanation, I have seen so far interface documents have not come across the appendix written very detailed, here can be used at will.

Conclusion:

This article divides the interface documentation into two modes:

1. Simple version: the core is how simple how to, how the project is tight or very hate to write people can use this way, the advantage is the delivery speed is fast, disadvantages, simple things may cause a lot of details of the neglect, sometimes write people will ignore, so still need to pay more attention to do not directly CV
2. Complex version: I don’t think many people want to write this kind of complex document. A document can be lost in half a day.

Personal is very like to write documents, on the one hand is to write documentation can improve their skills, and at the same time and feynman learning method is very apt, can be reviewing and summarizing ideas through writing process, on the other hand, a good document really can save time cost in the future, imagine how you can be in when someone asks you to jilt a document to solve the problem of time, You can give yourself a lot of time to reduce the cost of communication. It is common to be interrupted in daily work, and it may save your life to change the code in the form of documentation.

In short, the purpose of this article is to share some of my personal thoughts on document writing. I wrote documents for a few months from my internship in the company. The process was very boring and monotonous, but when I look back and see my achievements. It’s kind of fulfilling.

This is the last post of the year. Individuals choose to exercise as an investment in their future. Here’s a picture to remember. Take your time…