1.2 Reading API Docs - Jodoo

Key Points

How to read API documents.

Preparation Before Class

Interface Test Tool

Prepare one interface test tool in advance, and you can select one from the following tools:

Postman (Optional)

Postman is the best interface test tool.

Click Download Postman App to go to the Postman download page, select the corresponding version (Operating system and 32/64 bits), and install it.

The browser will automatically recognize your computer system, as shown below. The download page of a computer (Android) is as follows:

Windows users need to choose a 32-bit or 64-bit version. You need to first check whether your computer is equipped with an x32 or x64 processor. If either version to select is unknown to you, you can check it in the computer settings.

For example, if your computer has a x64 processor, click Windows 64-bit, directly open the ZIP, and install it.

Before opening the software, you need to register an account by filling in the email, username, and password. Tick the two boxes under the Password text box and then click Create free account to register a free account.

Hoppscotch (Optional)

Hoppscotch is a free, open-source, lightweight, fast, and beautiful API debugging tool, used to replace Postman. This tool can help programmers save time and improve work efficiency.

Click Hoppscotch, and you can use it.

Apizza (Optional)

An interface collaboration management tool used especially among geeks.

Click Apizza.

ApiPost (Optional)

ApiPost is an API debugging and management tool that supports team collaboration and can directly generate documents. It supports simulating common requests such as POST, GET, and PUT, which is a rare tool for backend interface developers or front-end and interface testers.

Click ApiPost.

Interface Preparation

For details about what API is, see API Definition.

For details about public interfaces, see API.

Course Content

How to View API Docs

API documents are generally divided into several parts: interface description, interface address, request method, request parameters, response content, error code, and instances:

Interface description: used to simply describe the logics and functions of interfaces. For example, there is an interface used to send messages and query the weather condition.

Interface address: It is a website address, or URL, which is called to give responses to the content.

Request method: Common request methods are GET and POST, and other methods are as follows:

Request parameters: used to transmit variables of information. Variables include field names and rules, in other words, selected fields, field types, and whether fields are required.

URL transferring parameters
Headers (Request headers)
Body (Request content)

Response content: field names and rules returned by interfaces

Error code: classify interface errors by codes to quickly identify the cause of the error and solve the problem.

Instance: the content of the response when interfaces are called.

GET and POST requests are important points.

GET Request

GET request is usually used to acquire the server's data.

The GET method concatenates parameters after the URL and parameters can only be transferred in the form of text.
The amount of data transferred is small, about 4kb (Different based on browsers).
Low safety and information will be shown in the address bar.
High speed and often used to requests with low security requirements.
GET request can include the Headers parameter.

Parsing a URL:

Request domain name (Host)

Request path:

(Some documents require their own domain names and paths, and others provide a complete interface address, such as Jodoo)

?: It represents starting to transfer parameters.
&: It represents the next parameter.
Request parameters:

Parameter Name	Value
Im	0
rn	10
pn	0
fr	search
ie	gbk
word	%BC%F2%B5%C0%D4%C6

In a GET request, the parameters/Params/Querys are transferred in the form of URL transferring parameters.

Note: In the app Postman, you can directly use URL to pass parameters, or fill in KEY and VALUE in Params, which will automatically be concatenated (demonstrated).

POST Request

Submitting data through a POST request is more secure than a GET request. (Note: Package capture software will also catch the content of the POST request, but you can encrypt it for high security requirements.)
The amount of data transmitted is large, and there is no requirement for data length in the request.
POST requests are used in occasions with high security requirements such as passwords, and in occasions with large amounts of submitted data, such as uploading files and publishing articles.

POST requests generally consist of URL, Headers, and Body. If there are Params/Queries in the interface document of a POST request, the parameters need to be transferred by URLs like GET requests. Parameters in the interface document of a POST request usually refer to Body.

Different request formats for POST requests:

Application/JSON, the JSON data format, usually uses raw-JSON. The most common format is JSON, which is the main format for our later call interfaces and self-developed interfaces.

As shown below, the key of parameter 1 is name, the value of parameter 1 is ziv, the key of parameter 2 is password, and the value of parameter 2 is 123.

{"name":"ziv","password":"123"}

As shown below, the key of parameter 1 is data_id and the value of it is 5398d19a9318483922.

{"data_id":"5398d19a9318483922"}

Text/xml (Understand). For the data format XML, raw-XML is generally used.

<?xml version="1.0" encoding="UTF-8" ?>
	<name>ziv</name>
	<password>123</password>

Multipart/form-data (Understand), which processes the data of the form into a message, with labels as units and separated by delimiters. Seperated by Boundary, you can upload files as well as key/value pairs through multipart/form data. It adopts a key-value pair approach, allowing uploading multiple files.
Application/x-www from urlencoded (Understand) will convert the data in the form into key/value pairs, separated by &.