Before writing interface documentation, I ask myself 3 questions

In order to make the interface documentation written by myself more concise and clear, it does not look like a rookie wrote it, I usually ask myself 3 questions before writing the interface .

Before we start a new interface, we need to make the following judgments:

• Is the request protocol HTTP/HTTPS?
• What is the format of the request body and response body (XML, JSON, FormData, Raw)?
• Is the API RESTful?

If the answers to the above three questions are clear, you can start adding an API interface.

API information

Fill in the request protocol, method, address, and name of the API at the top of the editing API;

Protocol support

HTTP/HTTPS

Request method support

• POST
• GET
• PUT
• DELETE
• HEAD
• OPTIONS
• PATCH

API request parameters

Set request headers <br>You can enter or import request headers.

In addition to manual input, you can also import request headers in batches. The data format is key : value , and the header information is one line at a time, such as:

 Connection: keep-alive
Content-Encoding: gzip
Content-Type: application/json
Date: Mon, 30 Dec 2019 20:49:45 GMT

set request body

The request body provides five types:

• Form-data
• Json
• XML
• Raw (custom text type data)

Set the Query parameter

The Query parameter refers to the address bar followed by a question mark? Later parameters, such as the user_name parameter in the following address:

 /user/login?user_name=jackliu

The data format of batch import is ?key=value... , and multiple parameters are separated by &, such as:

 api.eolinker.com/user/login?user_name=jackliu&user_password=hello

Set REST parameters

REST parameters refer to parameters whose address bar is separated by slashes/, such as the user_name and user_password parameters wrapped in curly brackets in the following address:

 /user/login/{user_name}/{user_password}

WARNING
Note that you only need to use {} to enclose REST parameters in the URL, the parameter name of the form does not need to fill in {}.

API response content

Setting Response Headers <br>You can enter or import response headers. The data format of batch import is key : value , header information one line at a time, such as:

 Connection: keep-alive
Content-Encoding: gzip
Content-Type: application/json
Date: Mon, 30 Dec 2019 20:49:45 GMT

set response content

The way of writing the response content is similar to that of the request parameters, and the response content provides four types:

• Json
• XML
• Raw (custom text type data)

The tool for writing interfaces used in this article is Eoapi , which is an open source api management tool that is lightweight and extensible.

Of course, if you think it is not enough to meet your needs, and if you have any good ideas, you might as well file an issue on Github , and the project developers will reply in time.

The project also has complete development documents. If you have any technical questions, you can also communicate, and PM will reply in time.

Github address: https://github.com/eolinker/eoapi
Documentation address: https://docs.eoapi.io/?utm_source=SF080401