How to write interface documents in the new ape 0 basic Python tutorial

Time:2022-5-26

When students learn python, the interface document is very important. The problem of the interface document directly affects our subsequent interface call and use. Let’s seriously study how to write the interface document.

#1. How HTTP carries information

– url

– headers

-Body: including request body and response body

#2 separate general information

Generally speaking, the information in headers is general and can be explained in advance as the default parameter

#3 parameter expression in path

The parameter expression in the URL uses [mustache]( https://github.com/janl/mustache.js )The parameter is wrapped in double braces ` {{paramname}}`

For example:

– `/api/user/{{userId}}`

– `/api/user/{{userType}}?age={{age}}&gender={{gender}}`

#4 data model definition

Data model definitions include:

-Path and query string parameter model

-Request body parameter model

-Response volume parameter model

Minimum data set of data model:

-Name

-Is it necessary

-Explain

>”Minimum data set” (MDS) is to better grasp the characteristics of a research object or the state of a thing or a job by collecting the least data. Its core is to establish a set of concise and practical data indicators for the observed objects. The concept of minimum data set originated from the medical field in the United States. The minimum data set comes from the need of information exchange, just like the need of information exchange between superior and subordinate quality and technology supervision departments, between enterprises and quality and technology supervision departments, and between quality and technology supervision departments and the public.

Some documents may include field types, but I don’t think it’s necessary. It is thought that the data transmitted by HTTP often needs to be serialized, and most of the data types are strings. Some special types, such as strings of enumeration types, can be described in the description.

In addition: ‘it is highly recommended to use tables to represent the data model’.

Take a chestnut

|Name | whether it must be described|

| ——– | ——– | ———————————————— |

|UserType | is the user type` Commom ` stands for ordinary users and ‘VIP ` stands for VIP users|

|Age | no | user age|

|Gender | no | user gender` 1 ` indicates male and 0 ` indicates female|

#5 request example

“`

// general 

POST http://www.testapi.com/api/user

// request payload

{

    “name”: “qianxun”,

    “age”: 14,

    “like”: [“music”, “reading”],

    “userType”: “vip”

}

// response

{

    “id”: “asdkfjalsdkf”

}

“`

#Exception handling

Minimum data set for exception handling

-Status code

-Explain

-Solution

Take a chestnut

|Status code | description | solution|

| —— | —————- | ————————– |

|401 | wrong user name and password | check whether the user name and password are correct|

|424 | the maximum online quantity is exceeded | please modify the maximum online quantity on the console|

I didn’t want to add the solution to the minimum data set of exception handling before, but for many developers, even if it knows that ‘424’ means’ exceeding the maximum online quantity ‘. If you don’t tell them how to solve the problem, they may ask you directly. So it’s best to be able to put it in place in one step and directly tell him how to solve it, so as to save time and effort.

#7 how to organize?

##7.1 an example of creating a user: creating a user

**1 request example**

“`

// general 

POST http://www.testapi.com/api/user/vip/?token=abcdefg

// request payload

{

    “name”: “qianxun”,

    “age”: 14,

    “like”: [“music”, “reading”]

}

// response

{

    “id”: “asdkfjalsdkf”

}

“`

**2 path and query string parameter model**

`POST http://www.testapi.com/api/user/{{userType}}/?token={{token}}`

|Name | whether it must be described|

| ——– | ——– | ———————————————— |

|UserType | is the user type` Commom ` stands for ordinary users and ‘VIP ` stands for VIP users|

|Token | is an authentication token|

**3 request body parameter model**

|Name | whether it must be described|

| —- | ——– | —————— |

|Name | is the user name. 4-50 characters|

|Age | no | age|

|Like | no | hobby. Up to 20|

**4 response volume parameter model**

|Name | description|

| —- | —— |

|ID | user ID|

**5 exception handling**

|Status code | description | solution|

| —— | —————— | ————————– |

|401 | token expired | please re apply for token|

|424 | exceeds the maximum number of people being created | please modify the maximum number of people being created on the console|

##7.2 reasons for such organization

1. ` request example ‘: the reason why the request example comes first is to use the’ fastest way ‘to tell developers how the interface should request

2. ‘path and query string parameter model’: use ‘mustache’ package parameters

3. ` request body parameter model ‘: if there is no request body, it can not be written

4. ‘response volume parameter model’:

5. Exception handling`

#8 form of document provision

The document proposal consists of the following two forms, ` online document ‘and ` PDF document’.

-` online documents`

-Easy update

-Easy to read at any time

-Easy to find

-Pdf document`

-Content performance is consistent and independent of document readers

-The document is read-only and will not be easily modified

Because it is facing third-party developers, ‘open online documents must be provided’; For some special reasons, it may be necessary to provide documents in the form of files. It is recommended to provide PDF documents. Of course, the following document forms are not recommended:

-Word document

-Markdown document

Word documents and markdown documents have the following disadvantages:

-‘the presentation of documents depends very much on the document viewer ‘: the presentation of word documents in different versions varies greatly. Documents with good content on your computer may be messy on others’ computers; The same is true for markdown files. Moreover, the files introduced into markdown can only rely on picture links. If the document contains pictures, they are likely to be lost.

-‘the document cannot be read-only ‘: if the document cannot be read-only, it may be inadvertently modified by third-party developers, so the accuracy of the document cannot be guaranteed.

To sum up, the key points of document form:

-‘read only ‘: ensure that the document will not be easily modified by developers

-‘consistency’: ensure the consistent content performance of documents on different devices and different document viewers

-‘easy version management’: DAAS: document as a software. Generally speaking, ‘software = data + algorithm’, but I think ‘document is also an important form of software’. Since software needs version management, document version management is also indispensable.