API overview

2022-11-22 02:47

WorldFirst offers a set of Application Programming Interfaces (APIs) that provides the ability for integration. You can use POST method to send HTTPS requests and receive responses accordingly.

The following section introduces the message structure and message transmission workflow.

Versioning

WorldFirst APIs are backward compatible. Earlier clients are adaptable to newer API releases.

Message structure

Before you make any request, it is important to understand how WorldFirst API works and how requests and responses are structured. This section provides general information (such as message structure, message fields, and message transmission) of online messages between a Partner and WorldFirst.

Request structure

The following figure illustrates the request structure.

Figure 1. Request structure

The following curl example depicts the general structure of a message:

copy
curl --location --request POST 'http://{domain_name}.com/amsin/api/v1/business/inquiryPayOrder' \
--header 'client-id: *****' \
--header 'Content-Type: application/json' \
--header 'signature: algorithm=RSA256,keyVersion=2,signature=KEhXthj4bJ8*****' \
--header 'request-time: now()' \
--header 'Cookie: JSESSIONID=66A1C5F430EA249ACD3B2A7EBA0*****' \
--data-raw '{"paymentId":"sample_payment_id"}'

Request URL

The requested URL is:

https://{host}/amsin/api/v1/{restfulPath}

where,

host is the standard domain name assigned by Platform.

restfulPath is the path to the interface.

An interface can be uniquely identified by restfulPath.

Request method

POST method is used to make an HTTP request.

Request header

The request header mainly contains the following fields:

Header field	Required	Code sample
Signature	Yes	Signature: algorithm=RSA256, keyVersion=2, signature=*****
Content-Type	Yes	Content-Type: application/json; charset=UTF-8
Client-Id	Yes	Client-Id: *****
Request-Time	Yes	Request-Time: 2019-04-04T12:08:56+08:00

Table 1. Request header

For details of each header field, see the following descriptions.

Signature

Signature contains key-value pairs that are separated by comma (,). Each key-value pair is an equation, which is a key joined with its value by an equal sign (=). A Signature is required for creating a request header.

The following keys can be configured:

algorithm: Specifies the digital signature algorithm that is used to generate the signature. The value is not case-sensitive. RSA256 and ECC224 are supported, and RSA256 is used by default.
keyVersion: Specifies the key version that is used to generate or validate the signature. By default, the value is the latest version of the key associated with client-Id.
signature: Contains the signature value of the request.

Example:

copy
signature: algorithm=RSA256, keyVersion=2, signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8*****

Content-Type

content-Type indicates the media type of the body of the request, as defined by RFC2616. In which, charset is used for generating/validating the signature and encrypting/decrypting content.

Example：

copy
content-type: application/json; charset=UTF-8

Client-Id

Required. client-Id is used to identify a client and is associated with the keys that are used for signature and encryption.

Request-Time

Required. request-Time specifies the time when the request is sent, as defined by ISO 8601.

Example:

copy
Request-Time: 2019-04-04T12:08:56+08:00

Request body

The request body contains the detailed request information in JSON format. Fields enclosed in the request body section vary depending on services. For more information, see the instructions of the specific message interface.

Response structure

The following figures illustrate the response structure:

Figure 2. Response structure

Response header

The response header carries the information about the response, mainly containing the following fields.

Note: Field names are case-insensitive.

Header field	Required	Code sample
Signature	Yes	Signature: algorithm=RSA256, keyVersion=2, signature=*****
Content-Type	Yes	Content-Type: application/json; charset=UTF-8
Client-Id	Yes	Client-Id: *****
Response-Time	Yes	Response-Time: 2019-04-04T12:08:56+08:00

Table 2. Response header

For details of each header field, see the following descriptions.

Signature

Signature contains key-value pairs that are separated by comma (,). Each key-value pair is an equation, which is a key joined with its value by an equal sign (=). Signature is required to create a response header.

The following keys can be configured:

algorithm: Specifies the digital signature algorithm that is used to generate the signature. The value is not case-sensitive. RSA256 and ECC224 are supported, and RSA256 is used by default.
keyVersion: Specifies the key version that is used to generate or validate the signature. By default, the value is the latest version of the key associated with client-id.
signature: Contains the signature value of the response.

Example:

copy
signature: algorithm=RSA256, keyVersion=2, signature=KEhXthj4bJ8*****

Content-Type

Content-Type indicates the media type of the response body, where charset is used for generating and validating signatures. For more information about the Content-Type field, see RFC2616.

For example：

copy
Content-Type: application/json; charset=UTF-8

Client-Id

Client-Id is a unique ID assigned by WorldFirst to identify a Partner and is associated with the keys that are used for the signature.

Response-Time

Specifies the time when the response is returned, as defined in ISO 8601.

Example:

copy
Request-Time: 2019-04-04T12:08:56+08:00

Response body

Response body contains the information responding to the client. Fields in this section vary depending on services. However, the result parameter, which indicates the result of an API call, is always contained.

When the result status ( resultStatus) is "Failed"(F) or "Unknown" (U), the result code ( resultCode ) indicates an error code, and the result message ( resultMessage ) indicates an error message, which is used for troubleshooting. For more information about how to resolve errors, see Error codes.

Field	Data type	Required	Description
resultStatus	String	Yes	Result status. Valid values are: `S` : Successful `F` : Failed `U` : Unknown
resultCode	String	Yes	Result code. Max. length: 64 characters
resultMessage	String	No	Result message that describes the result code in detail. Max. length: 256 characters

Message transmission workflow

The following figure illustrates the message transmission workflow from Partner to WorldFirst.

Figure 3. Message transmission workflow

Overall procedure

Follow the overall procedure to call an API.

Preparations

Sign the request before sending.
To prevent some potential errors that you might get in the response, consider the following factors:

Properly encode the data.
Enable API idempotence.

1. Construct a request

Construct a request by complying with the request structure, for example, by adding the Client-Id, Request-Time, Signature, and other fields to the request header.

To ensure message transmission security, message signing and signature validation are required for all requests and responses.

2. Send a request

After the request is properly constructed and signed, the Partner can send the request to WorldFirst.

3. Check the response

The response is returned usually in JSON or XML format. For details about the response, see the Response structure section.

After you receive the response, validate the signature of the response.

4. Check the status code

The response data may vary depending on the services. However, the result field, which indicates the result of an API call, is always contained. If an error occurs, an error response is returned, where the result object indicates the error code and error message for you to troubleshoot issues.