Background

To enhance data security of the AliExpress platform and sellers, as well as to improve the efficiency and quality of interconnection between open platforms, the original AliExpress open platform has been completely migrated and upgraded to a new open platform which is called TOP (Taobao Open Platform).

Migration Procedure

1. Register developer account on new platform (TOP)

First please take a look at AliExpress Open Platform Introduction and check which type of developer you are. If you are not clear about the developer type, please don’t hesitate to get help from your AliExpress business contact or AliExpress open platform support (Dingtalk group ID: 23371186). And then you can follow the process to register developer account and apply for open platform applications.

2. Migrate your application from Ocean platform to TOP platform

Here we will see the difference between these two platforms and what you need to pay attention to during the migration.

Authorization

Both Ocean and TOP are based on OAuth 2.0. The authorization for Ocean platform is:
1. Get temporary token (code)
2. Get refresh token and access token by temporary token
3. Refresh access token by refresh token after access token is expired
4. Start from step 1 if both tokens are expired

In TOP platform, step 3 is not necessary because the validity period of access token in TOP (1 year for Self-Developed applications and 1 month for Commercial Developer applications) is much longer than in Ocean (10 hours), and the refresh token is already expired when you get it, which means it’s useless.

Please refer to TOP User Authorization Introduction for more details

Note

• The redirect_uri parameter during authorization process must match the callback URL defined in console, please refer to User Authorization - redirect_uri.

API invoke

API access count limitation

Both Ocean and TOP have limitation for API calls, but you will face more problems on this in TOP platform. So be aware of this, please refer to API access count limitation.

SDK

TOP performs better than Ocean on SDK support.

• TOP SDK covers all the APIs. If there is any API change, you can generate the SDK again by yourself and then have the latest updates.
• TOP supports more types of SDK, including Java, PHP, Python, .NET, Metadata, C and NodeJS.
• TOP Java SDK and .NET SDK supports receiving messages from TOP platform. You only need to deal with the business, needn’t care about the underlying stuff. But, unfortunately, TOP doesn’t support messaging service outside China. We will push the oversea deployment of messaging service.

Though SDK provides convenience for interaction with AliExpress API, you need to consider the deployment issue, especially when you need to deploy your module together with AliExpress SDK to each client.

• Usually we will ensure backward compatibility when we change APIs or create new APIs.
  • If you don’t use the new features, you needn’t deploy new SDK.
  • If you want to use the new features, you need to change your module and deploy it to clients, so deployment of SDK is not an additional work.
• SDK will do some parameter validations on client side, such as checking required parameters, list size limitation. So if we loosen parameter restrictions, you need to redeploy the SDK if you want to take benefit of it, while no change is required if you’re using direct API instead of SDK.
  • If you don’t do any parameter validation in your part, you need to deploy the SDK to clients, even you haven’t changed your module.
  • If you do the same parameter validation in your part, you need to change your module and deploy it to clients, so deployment of SDK is not an additional work.

API Difference

For most of the API, we only change them from one platform to another platform, the function and input/output are the same logically. Below are the major differences between Ocean APIs and TOP APIs.

API name

All API names are changed. For example, API to upload images, its name is “api.uploadImage4SDK” in Ocean while it’s “aliexpress.photobank.redefining.uploadimageforsdk” in TOP.

• Prefixes are different
• The last part of the API may be the same except TOP APIs are of lower case
• TOP doesn’t support numbers in API name, so if there is number in API name, it will be changed to letters

Parameter

name

Ocean APIs use camel case for parameter name while TOP APIs convert each upper case character to underscore character and lower case character. For example, for posting product in native language, Ocean parameter name “aeopAeProductSKUs” is named as “aeop_ae_product_s_k_us” in TOP.

data type

TOP supports below basic data types which are not all the same as data types in Ocean.

• String
• Number
• Boolean
• Date
• byte[]
• Json
• byte

Response format

List

A list parameter in API is mapped to a JSON array in Ocean while it’s mapped to a JSON object with a sub JSON array in TOP (JSON format). For example, in aliexpress.freight.redefining.listfreighttemplate, the aeop_freight_template_d_t_o_list is a list.

The response in TOP is

There is a middle layer aeopfreighttemplatedtolist between aeop_freight_template_d_t_o_list and the JSON array. The name of the middle layer is the lower case of the type name (here it’s Aeopfreighttemplatedtolist).

Error response

There are two kinds of errors in Ocean

• Platform errors, Ocean will return response like below when there are platform errors.

  {
  "error_code":"450",
  "error_message":"Required argument productId : expect [type: java.lang.String]",
  "exception":"Required argument productId : expect [type: java.lang.String]"
  }

• API errors, each API can define its own error response
  

TOP also has those two kinds of errors, but it’s recommended to merge them into consistent format like below

{
	"error_response":{
		"sub_msg":"invalid parameter",
		"code":50,
		"sub_code":"isv.invalid-parameter",
		"msg":"Remote service error"
	}
}

however, some APIs don’t follow this rule and still use their own error responses

So when there is API’s own error response, you need to check both platform defined error and API error, otherwise you only need to handle the platform defined error.

FAQ