Publish API Project

If you are an API provider and provide high-quality API resources, you only need the following steps to easily publish your API.

Preparation

In order to better unified management and maintenance of APIs, we have the following requirements for accessed APIs:

1. Need to return JSON format
2. The top-level fields of response need to meet the following requirements

Name	Description
code	(Required) Return code. The return result is determined based on this field. See the table below for detailed meaning.
forceDeduct	(Optional) If forceDeduct = true, the credits/fees will be forced to be deducted. If forceDeduct = false or not passed, use code field to determine whether to deduct the credits/fees
result	(Optional) The complete original return result, field structure and explanation should be provided by the supplier
msg	(Optional) Reason for request failure
creditsDeduct	(Optional) When using a dynamic pricing plan, use this field to return the credits deducted. This value cannot exceed 0.2 by default.

Deduction Rule

Sometimes the code field is not suitable for determining whether credits/fees should be deducted. For this situation, we have added the forceDeduct field.

When forceDeduct = true or code = 0, the credits/fees will be deducted

Considering the actual situation, we will count the number of successful requests based on forceDeduct = true or code = 0

We will construct the response returned to the user based on the above fields, for example:

Provider response

{
  "code": 0,
  "result": {
    "data": "sample"
  },
  "otherField1": "value1",  // This field will be ignored
  "otherField2": "value2"  // This field will be ignored
}

Platform response

{
  "code": 0,
  "credits": 0.001,  // assume unit price = 0.001USD
  "result": {
    "data": "sample"
  }
}

The response sample for a failed request is as follows:

Provider response

{
  "code": 1000,
  "msg": "Reason for request failure",
  "otherField1": "value1",  // This field will be ignored
  "otherField2": "value2"  // This field will be ignored
}

Platform response

{
  "code": 1000,
  "msg": "Reason for request failure",
}

TIP

It should be noted that response status will not be checked.

3. code字段的含义与解释

code	description
0	Request successful, will consume credits according to the pricing plan.
1000	Internal error
1001	Parameter error
1002	The requested resource does not exist and may be deleted.
1003	Internal processing is busy, please retry later
1004	Insufficient permissions (Usually returned by platform)
1005	Insufficient balance (Usually returned by platform)

Steps

1. Create Project

Enter the console Merchant, click Create Project, and select API as product type.

After creation, click the project to enter the management page

2. Fill in basic project info

Enter the project to complete the relevant configurations. You can upload your own project cover image, and click Save to take effect.

3. Create API Endpoint

TIP

For better user experience, it is strongly recommended to fill in the Response Docs Link to describe the field structure and explanation in result.

The Slug field is the API sub-path of the Endpoint and cannot be duplicated. It is recommended to fill in a path with business meaning.

The Backend URL is the API URL provided by merchant, this field is not public.

Params Schema & Json Schema

Params Schema and Json Schema have the same structure and are used to describe parameter information and automatically generate documents. Json Schema should not be configured for GET requests.

We will check whether the required parameters are missing. This is only the most basic parameter check. There is no guarantee that the user has passed the correct parameters. Therefore, you should also verify the parameters.

Field	Required	Description
name	true	field name
required	true	determine whether the parameter must be passed, bool value
type	false	field type, has the following values: ["number", "string", "file", "array", "object", "int", "long", "date", "boolean"]
defaultValue	false	field default value, it is recommended to fill in when the parameter are not required
desc	false	field description
example	false	field example

examples

[
  {
    "name": "bindId",
    "desc": "bind user ID",
    "required": true,
    "defaultValue": "",
    "type": "string",
    "example": "123"
  },
  {
    "name": "productId",
    "desc": "product ID",
    "required": true,
    "defaultValue": "",
    "type": "string",
    "example": "123456"
  }
]

4. Configure Pricing Plan

TIP

When setting the last stage price to 0 for stage pricing, it can be equivalent to the daily price.

Dynamic Pricing requires the creditsDeduct field in the API return fields to specify the cost of this call.

Dynamic pricing limits

Due to the uncertainty and risks brought by the dynamic pricing plan, we stipulate that the maximum dynamic price for a single request cannot exceed 0.2 USD. If it exceeds, it will still be billed at 0.2 USD

If you select a dynamic pricing plan but do not pass the creditsDeduct field, no deduction will be made.

5. Publish

Go to the project page and set the Status = Online to complete the online process. The platform will also automatically generate API documents based on the project configuration information.

Finally

The API configuration will take effect immediately after modification, so please operate with caution, especially do not easily modify configurations such as Slug, Status, etc. that will affect current users.