Common Requests

This section describes the request structure of REST APIs for SwiftFederation solutions. All the requests to the REST APIs of SwiftFederation solutions will share the the same common structure to include Request-Line, Request Headers and Request Body.

Request =   Request-Line
            Request Headers
            CRLR
            Request Body

In this document, we use CRLR to represent "\r\n" (carriage return and linefeed), and SP to represent ' ' (spce character).

Request-Line

The Request-Line begins with a method token, followed by the Request-URI and the protocol version, and ending with CRLR ("\r\n", carriage return and linefeed). The elements are seperated by a SP (' ', space character).

Request-Line =  Method Request-URI HTTP/1.1 CRLF 

# i.e.
#               GET /index.html HTTP/1.1

Method

SwiftFederation solutions uses the HTTP methods below to interact with the API endpoints.

Method	Description
GET	Retrieves data from the API endpoint.
POST	Creates or updates the resources identified by the API endpoint with the payloads included in the request body.
PUT	Updates or replaces an existing resource.
DELETE	Removes a resource from the server.
HEAD	Similar to GET but does not return the response body. It is used to check the headers and metadata of a resource, often for testing or validation purposes,
PATCH	Makes a partial update on a resource.

Request-URI

SwiftFederation solutions utilise standard URIs to locate the specific endpoints for all API requests. A standard URI will be formatted as an absolute URI or an absolute path.

absolute URI

The absolute URI is usually REQUIRED when the request is being sent to a proxy in a format below:

protocol://host[:port]/path[?query parameters]

Parameter	Required	Description
protocol	Mandatory	The protocol used for sending requests can be either HTTP or HTTPS. HTTPS is recommended for secure access to the API endpoint.
host	Mandatory	Domain name or IP address of the API endpoint for SwiftFederation solutions.
port	Optional	Optional to indicate which port the host is available on. If no port number is specified, the protocol uses the default value (HTTP: 80, HTTPS: 443).
path	Mandatory	The specific location of the requested API endpoint.
query parameters	Optional	Optional key-value pairs as the request parameters to the API endpoint.

Absolute path

The absolute path is the most common form of Request-URI to identify a resource on the API gateway. Along with the absolute path, a HTTP header of "Host" will be transmitted to identify the network location of the URI:

/path[?query parameters]

Parameter	Required	Description
path	Mandatory	The specific location of the requested API endpoint.
query parameters	Optional	Optional key-value pairs as the request parameters to the API endpoint.

Request Headers

Providing the essential information when firing a call to the API endpoints, the Common Headers below MUST be added in all requests to the REST APIs of SwiftFederation solutions for the authentication purpose. The API Gateway will use the common headers to validate the signature.

Common Headers

HTTP Header	Type	Required	Description
Content-Type	string	Mandatory	The content type of the request. Fixed as application/json; charset=utf-8.
Host	string	Mandatory	Specifies the Internet host and port number of the resource being requested
Authorization	string	Mandatory	The credentials that authenticate a user agent with the API gateway allow access to the API endpoint. Check "Signature" for details.
X-SFD-Date	string	Mandatory	The date and the time at which the request originated, in a format of "yyyyMMdd'T'HHmmss'Z', e.g. 20180328T173013Z. The discrepancy between X-SFD-Date and the API gateway should be less than 1 hour.
X-SFD-Nonce	long	Mandatory	A cryptographic random number for one-time usage to prevent replay attacks. The length can be 5 to 18 digits.
X-SFD-Signature-Version	string	Mandatory	The version of the signature, fixed as 2.

Custom Headers

An API call could create and add custom headers as header parameters when sending to the API gateway. For each custom header,

• If the header name starts with "X-SFD-", i.e. "X-SFD-FZone", the custom header will be included in the "CanonicalHeaders" to generate the signature
• Otherwise, the custom header will not be included in the "CanonicalHeaders" when generating the signature.

Request Body

The request body contains the request payload in JSON format. The schema of the JSON object varies according to the request types, each of which will have its own payload schema specifically defined in the corresponding API documentation.

Request Parameters

Based on the parameter location, the client could pass the request parameters to the API in 5 types:

• Path Parameters, such as /v1.1/customer/{customer_id}
• Query Parameters, such as /user?role=admin&location=SG
• Header Parameters, such as X-SFD-Date: 20250725T023747Z
• Cookie Parameters, such as Cookie: type=1; token=SPe28ioladkDC
• Body Parameters, such as { "name": "jike", "location": "SG" } in JSON format

Refer to Request Parameters on how to pass parameters to REST APIs of SwiftFederation solutions.

Request Example

GET /v1.1/customer/35394 HTTP/1.1
Host: open-api.swiftfederation.com
Content-Type: application/json; charset=utf-8
Authorization: HMAC-SHA256 O80ybSq26xUE383u:3ebba5b79c247db566d957638ecc9d085d4805a957f84ad8114af721635a41a7
X-SFD-FZone: SG
X-SFD-Date: 20250806T045529Z
X-SFD-Nonce: 15121
X-SFD-Signature-Version: 2

Best Practices

Rate Limiting

Configure the rate limits posed by the API gateway on a REST API in the specific API document, such as:

• 100 requests per minute
• 1000 requests per hour

Security

• Always use HTTPS for API requests to prevent man-in-the-middle (MITM) attacks or the leakage of important service data.
• The access key is critical to call the REST APIs of SwiftFederation solutions to change or delete all service data. Any leakage of the access key may compromise service and data security. Store keys securely and apply strict permission management to prevent any key exploitation.

Validation on Request Parameters

• Validate Request Parameters in URI path, query string, headers, cookie, and request body before sending an API request.
• Ensure the API request is correctly signed.