How to connect the api interface

In daily work, we often encounter a scenario where company A wants to connect to company B’s API method. This article is from the perspective of company A to actually connect the API interface of company B.

1. Background

In daily work, a scenario often encountered is: Company A wants to connect to Company B's API method. At this time, Company A needs to read Company B's interface document and find the API it needs to connect to from the interface document . And according to the requirements of the interface document, complete the coding work, and finally complete the docking work.

This article is from the perspective of company A, and the actual combat of connecting the API interface of company B.

2. Understand the basic conventions of company B’s interface

Under normal circumstances, Company B will give the following similar agreements to meet the basic docking, and will provide two sets of information for the test environment and the formal environment.

appkey: Company A’s merchant platform registration id

appsecret: the secret obtained by Company A’s merchant platform

3. Basic domain name

Under normal circumstances, Company B will provide two basic domain names: test environment and production environment.

For example:

Test environment: https://******.com.cn

Production environment: https://******.com.cn

4. Request and corresponding format description

Under normal circumstances, Company B will provide the request and corresponding basic format instructions.

For example:

1. Request method

post

2. Request message format

application/json

3. Response message format

application/json

4. Request public parameters

For example, Company B has the following requirements

All interfaces need to pass the following parameters in Http Header mode;

name	type	must	describe
key	String	yes	Call key (must be spliced ​​into the URL in GET mode)
secret	String	yes	call key
api_name	String	yes	API interface name (included in the request address) [item_search, item_get, item_search_shop, etc.]
cache	String	no	[yes,no] The default is yes, which will call cached data and is faster.
result_type	String	no	[json,jsonu,xml,serialize,var_export] returns the data format, the default is json, the content output by jsonu can be read directly in Chinese
lang	String	no	[cn,en,ru] translation language, default cn simplified Chinese
version	String	no	API version

Of course, the parameters offered by different companies vary and vary from company to company.

5. Response/callback parameter description

For example: all APIs of company B have responses, and some APIs also have callback responses. Whether they are responses or callback responses, their parameter formats are the same.

name	type	must	Example value	describe
item	item[]	1		Baby details data
num_id	Bigint	1	520813250866	Baby ID
title	String	1	Three-blade wooden folding knife that passes security check, creative mini keychain, key knife, saber, portable multi-functional knife, free shipping	baby title
desc_short	String	0		Product Description
promotion_price	Int	0		Special price
price	Float	1	25.8	price
total_price	Float	0	0
suggestive_price	Float	0	0
orginal_price	String	0	25.80	original price
nick	String	0	Happy Shopping Inn	Shopkeeper's nickname
num	Int	0	3836	in stock
my_num	Int	0	0	Minimum purchase quantity
detail_url	String	0	http://item.taobao.com/item.htm?id=520813250866	baby link
pic_url	String	1	//gd2.alicdn.com/imgextra/i4/2596264565/TB2p30elFXXXXXQXpXXXXXXXXXX_!!2596264565.jpg	baby pictures
brand	String	0	three-blade tree	brand name
brandId	Int	0	8879363	Brand ID
rootCatId	Int	0	50013886	Top level category ID
cid	Int	1	50014822
crumbs	Mix	0	[]	Navigation menu
created_time	String	0
modified_time	String	0
delist_time	String	0
desc	String	0		product details
desc_img	Mix	0	[]	Product details pictures
item_imgs	Mix	0	item_imgs[]	product picture
item_weight	String	0
item_size	String	0
location	String	0		Place of shipment
express_fee	Float	0	0.00	Courier fees
ems_fee	Float	0		EMS cost
post_fee	Float	0		Logistics costs
shipping_to	String	0		Ship to
has_discount	Boolean	0	false	Is there any discount?
video	video[]	0		Product video
is_virtual	String	0
is_promotion	Boolean	0	false	Promotion or not
props_name	String	0	1627207:1347647754:颜色分类:长方形带开瓶器+送工具刀卡+链子;1627207:1347647753:颜色分类:椭圆形带开瓶器+送工具刀卡+链子;	商品属性名。格式为pid1:vid1:name1:value1;pid1:vid2:name2:value2。
prop_imgs	prop_imgs[]	0		商品属性图片列表
property_alias	String	0	20509:9974422:36;1627207:28326:红色;20509:9975710:38;1627207:28326:红色;20509:9981357:40;1627207:28326:红色	销售属性值别名。格式为pid1:vid1:alias1;pid1:vid2:alia2。
props	Mix	0	[{ "name": "产地","value": "中国" }]	商品属性
total_sold	Int	0
skus	skus[]	0		商品规格信息列表
seller_id	Int	0	2844096782	卖家ID
sales	Int	0	138	销量
shop_id	Int	0	151372205	店铺ID
props_list	Mix	0	{20509:9974422: 尺码:36}	商品属性
seller_info	seller_info[]	1		卖家信息
tmall	Boolean	0	false	是否天猫
error	String	0		错误信息
warning	String	0		警告信息
url_log	Mix	0	[]
favcount	Int	0	0
fanscount	Int	0	0
method	String	0	item_tmall:pget_item
promo_type	String	0
props_img	Mix	0	1627207:28326": "//img.alicdn.com/imgextra/i2/2844096782/O1CN01VrjpXt1zyCc9DvERE_!!2844096782.jpg	属性图片
shop_item	Mix	0	[]
relate_items	Mix	0	[]

6、针对异步回调的说明

例如：B公司对异步回调说明如下：

异步回调：

Some specific interfaces need to return results asynchronously, so Merchant A needs to provide a callback address, base64 encode it, and configure it in the callback_url in the HTTP request header.

Response mechanism:

The response mechanism means that when merchant A receives the data notification from company B, it must write back the success string, which is not case-sensitive. When company B receives the "success", it will consider that merchant A has received the notification; otherwise, it will continue to repeat the request. Call back the interface 3 times, with time intervals of 1s, 5s, and 30s. If access fails 4 times, the callback will continue to be polled every 3 hours.

Callback decryption:

The callback is encrypted using AES and needs to be decrypted before use. To avoid callback failure due to network fluctuations and if you have not received a callback for a long time, please take the initiative to inquire.

7. Request body encryption instructions and examples

The data is encrypted using AES and is used as the value of data after encryption.

Example:

Before encryption:

After encryption:

8. Callback decryption instructions and examples

The data is decrypted using AES, and the data value part is decrypted. After decryption, it is a json string.

Before decryption:

After decryption:

9. Generally, Company B will also explain the code value.

5. Determine which APIs to connect to

Under normal circumstances, Company B will provide the necessary APIs for a certain project, and we often only need to connect to a small number of API interfaces. Therefore, we must first confirm which API methods we want to connect to. We only need to connect according to the requirements of the API.

6. Write some basic tool classes according to the API documentation

Tools are divided into two categories. For the first category of tools, Company B will provide a DEMO, and we can just use it. The other type needs to be written by yourself according to the API requirements.

7. Write the necessary DTO according to the API documentation

For each API, it mainly includes request DTO, response DTO, and callback response DTO. This requires tracking the API requirements and writing DTO that meets the requirements.

Of course, some DTOs can be abstracted into a class. For example, the general response DTO and the callback response DTO are the same. At this time, they can be abstracted into a DTO.

8. Connect each API method

After completing the above preparations, you can connect the interfaces one by one. You can use the following method to connect interfaces one by one.