API overview

2024-11-21 06:55

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.

For a full list of all the available APIs, refer to the API list chapter.

Versioning

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

Message structure

Request structure

An API Request is composed of the following structure:

Name	Description
Request URL	`https://{domain_name}.com/amsin/api/v1/{restfulPath}` `domain_name` is the standard domain name assigned by Platform. `restfulPath` is the path to the interface. Note: The following domain names are available for integration with WorldFirst: SG: open-sea.worldfirst.com EU: open-eu.worldfirst.com US: open-na.worldfirst.com
Request Method	`POST`
Request header	Composed of : `Signature` `Content-Type` `Client-Id` `Request-Time` Refer to the table down below for more details.
Request body	Request body is in JSON format. Sample: `{"quoteBizScene": "REF_QUOTES"}`

A request header contains the following fields:

Name	Sample	Description
Signature	signature: algorithm=RSA256, keyVersion=2, signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGRrWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m%2FOW4UQVmXaQ9yn%2Fw2dCtzwAW0htPHYrKMyrTpMk%2BfDDmRflA%2FAMJhQ71yeyhufIA2PCJV8%2FCMOa46303A0WHhH0YPJ9%2FI0UeLVMWlJ1XcBo3JrbRFvcowQwt0lP1XkoPmSLGpBevDE8%2FQ9WnxjPNDfrHnKgV2fp0hpMKVXNM%2BrLHNyMv3MkHg9iTMOD%2FFYDAwSd%2B6%2FEOFo9UbdlKcmodJwjKlQoxZZIzmF8w%*****	`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.
Content-Type	Content-Type: application/json; charset=UTF-8	`content-Type` indicates the media type of the body of the request, as defined by RFC2616. `charset` is used for generating/validating the signature and encrypting/decrypting content.
Client-Id	Client-Id: ****	Identify a client that is associated with the keys that are used for signature and encryption.
Request-Time	Request-Time: 2019-04-04T12:08:56+08:00	Specifies the time when the request is sent, as defined by ISO 8601.

Note: Access-Token is used for OAuth in some API request headers. Please refer to OAuth for detailed information.

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

copy
curl -X POST \
  http://{domain_name}.com/amsin/api/v1/payments/inquiryQuotes \
  -H 'Content-Type: application/json; charset=UTF-8' \
  -H 'Client-Id: *****' \
  -H 'Request-Time: 2019-04-04T12:08:56+05:30' \
  -H 'Signature: algorithm=RSA256, keyVersion=2, signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjx*****' \
  -d '{
  "quoteBizScene": "REF_QUOTES"
}'

The following figure illustrates the request structure:

Figure 1. Request structure

Response structure

An API Response is composed of the following structure:

Name	Description
Response header	Composed of : `Signature` `Content-Type` `Client-Id` `Response-Time` Refer to the table down below for more details.
Response body	In JSON format. A result parameter is included in the response body, which includes a `resultStatus`, `resultCode`, and `resultMessage`. Use these parameters for troubleshooting.
HTTP Response Status	Sample: `200 OK`

The following figures illustrate the response structure:

Figure 2. Response structure

Procedures to make an API call

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

Figure 3. Message transmission workflow

Step 1. Construct a request

Properly construct a request with matching structures.
Sign the request.
Enable the Base64 encoding.

Step 2. Send a request

Assemble the request and send it to the WorldFirst server.

Step 3. Check the response

Validate the signature of the response after receiving the response message.

Step 4. Check the status code

In the event that an error occurs, an error response is returned, in which the result object indicates the error code and error message for the purpose of troubleshooting.