Introduction

This section covers the general principles of calling the TOP open API via HTTP . Developers can call the API by first assembling the URL with a certain format, or by using the platform provided SDK. (SDK is automatically generated and includes functions like composing request, encryption etc. Using SDK to invoke the APIs is very simple and straightforward, it is recommended for the users. )

 

 

API Calling Entrance

An API calling entrance is a URL address for calling open APIs. The open platform provides two ways of API calling entrance. Developers can choose either one of them.

Production environment corresponds to online data, and sandbox environment corresponds to test data. Two are separated, has separate AppKey, AppSecret, and other parameters.

HTTP Gateway Entrance:

Sandbox environment gateway: http://gw.api.tbsandbox.com/router/rest

Taobao Production environment gateway: http://gw.api.taobao.com/router/rest

 Calling Parameters

Calls to the API must include system parameters in addition to the parameters associated with the application.  Different application specific parameters are needed for different specific APIs. Following is an example of a taobao.user.seller.get API.

System Parameters

 Following table is detailed description of the system parameters.

Name	Type	Required	Description
method	string	Y	Name of the interface
timestamp	string	Y	Timestamp, required format is yyyy-mm-dd HH:mm:ss(e.g., 2013-05-06 13:52:03). The Taobao API server allows a maximum time difference from server of 6 minutes.
format	string	N	Desired response format, defaults to xml. Supports xml or json.
app_key	string	Y	AppKey provided by Alibaba. Each partner will be assigned a unique key for accessing the API
v	string	Y	API protocol version – this can be set to “2.0”
sign	string	Y	Signature generated by encrypting the input parameters (see Signature section below for details)
sign_method	string	Y	Encryption method used for generating the signature. Supports md5 or hmac
Session	string	N	1. SessionKey (or Access Token) is issued by TOP after OAuth2.0 process.

 Application Parameters

Name	Type	Required	Description
Fields	string	Y	Parameter for the specific API. Here is the nick name of the seller in this api.

Signature

Calls to the API requires signature verification of the parameters, and the TOP server will also verify whether the call parameters are valid.

The method is as follows: Arrange all request parameters (except images and signature) into alphabetical order and concatenated together: key + value … key + value Example: foo=1, bar=2, baz=3 would become bar2baz3foo1

The values should then be encrypted using either MD5 or HMAC as follows:

MD5: Concatenate the appSecret to the front and back of the string to be signed, apply the MD5 hash, then convert to uppercase. byte2hex(md5(appSecretbar2baz3foo1appSecret))

HMAC: Use the MD5 function of HMAC. byte2hex(hmac (appsecret, bar2baz3foo1))

 Example

This example demonstrates a client using the taobao.user.seller.get API method to request details about a seller whose member ID is “nick”. In this case, assume the client’s app_key, appSecret and session all have the value “test”.

 1）Input parameters:
       method=taobao.user.seller.get
       timestamp=2013-05-06 13:52:03
       format=xml
       app_key=test
       v=2.0
       fields=nick
       sign_method=md5
       session=test

 2）Sort by parameter name:
       app_key=test
       fields=nick
       format=xml
       method=taobao.user.seller.get
       session=test
       sign_method=md5
       timestamp=2013-05-06 13:52:03
       v=2.0
       3）Concatenate key-value pairs:
Concatenate all value-key pairs, then append the appSecret to both the beginning and end of the string:
       testapp_keytestfieldsnickformatxmlmethodtaobao.user.seller.getsessiontestsign_methodmd5timestamp2013-05-06 13:52:03v2.0test
       4）Generate the signature:
32 character capital-case MD5 -> 72CB4D809B375A54502C09360D879C64
       5）Assemble the HTTP request:

       http://gw.api.taobao.com/router/rest?sign=72CB4D809B375A54502C09360D879C64&timestamp=2013-05-06+13%3A52%3A03&v=2.0&app_key=test&method=taobao.user.seller.get&format=xml&session=test&fields=nick

Implementation Examples

Language	URL
Java	//open.taobao.com/doc/detail.htm?spm=a219a.7386781.0.0.x1M0Ir&id=130
PHP	//open.taobao.com/doc/detail.htm?spm=a219a.7386781.0.0.x1M0Ir&id=131
.Net	//open.taobao.com/doc/detail.htm?spm=a219a.7386781.0.0.x1M0Ir&id=132

Important Notice:

1.     All the request and response contents are utf-8 encoding.

2.     Products and public information enquiry APIs are recommended through HTTP get request. Trading, privacy information, and modification APIs are recommended through HTTP post request.

3.     Sandbox and Production environments are different, they use different appkey, appsecret, and session.

Sign the request is only required if composing the HTTP URL manually. If developers use SDK, this has already been implemented in the SDK.

FAQ

关于此文档暂时还没有FAQ