SGDex API (1.2.0-release)

This section gives an introduction to SGDex.

SGDex stands for "Singapore Data Exchange".

SGDex is a highly-customisable data exchange layer platform that supports multiple data exchanges. In other words, you can use SGDex as a data exchange layer for any platform of your choice.

SGDex is organised around REST and returns JSON-encoded responses with standard HTTP response codes.

SGDex is highly configurable according to your data needs. Each data exchange can customise and configure APIs according to their usage. If an entity in a data exchange wants to send or receive data, they can call one of the pre-configured REST APIs in the data exchange, and the routing is handled by us.

The diagram above illustrates how SGDex can support your application. SGDex currently supports Singapore Financial Data Exchange(SGFinDex) and Singapore Trade Data Exchange (SGTraDex).

For example, SGFinDex has an admin portal that directly interacts with the APIs provided by SGDex for configuration and organisational purposes. It also provides a group of internal APIs that can communicate with admin-configured APIs in SGDex. For SGTraDex, they also have a similar design. However, instead of a group of APIs, they provide a pitstop portal for communication between SGDex and SGTraDex.

Key Roles in a Data Exchange

In every data exchange, there are 3 key roles: Admin, Provider and Consumer.

The diagram above illustrates the 3 key roles in a data exchange. The following explains what each role does:

• Admin: configures and organises the list of APIs, Topics, and Directories within a data exchange

• Providers: provides data to a data exchange. Providers can manage their:

  • System: pushes data to Consumers
  • Endpoint: allows for Consumers to pull data from a Provider

• Consumers: consumes data from a data exchange. Consumers can manage their:

  • Client Application: pulls data from Providers
  • Webhook: receives data pushed from Providers

Each role listed above has a specific set of APIs that it can call to interact with the data exchange. Admin, Providers and Consumers generally call APIs used for Organising and Configuring Your Data Exchange. On the other hand, Systems, Endpoints, Client Applications and Webhooks generally call APIs used during the actual Routing .

This section explains the configurations and organisations the Admin, Providers and Consumers can make in a data exchange.

Terminology

Listed below are some common terms used when organising a data exchange.

• API: an endpoint that a Consumer's Client Application in a data exchange can send a request to in order to retrieve data from Providers' Endponts.
• Topic: an endpoint that a Provider's System in a data exchange can send data to in order to send this data to listening Consumers' Webhooks.
• Usecase: a group of Topic(s) and API(s) that serve a similar purpose or are part of a similar process.

How to Organise Your Data Exchange

This section illustrates how the terminologies (listed in the previous section) in a data exchange are related. The diagram below shows how APIs, Topics, and Usecases are related.

As seen in the diagram above, Usecases are used for organising the APIs and Topics in a data exchange. A Usecase will contain all APIs and Topics you can create under a Usecase.

How to Configure Your Data Exchange

With your data exchange created and organised according to your needs, you will then need to configure the API(s) and Topic(s) in your data exchange to behave how you want them to when routing information. In this section, we explain what Scopes, Enrolments and Subscriptions are and how they are related to APIs and Topics.

Scopes

Each OAuth API has a Scope, which is a list of data items that an API can return to a caller when it is called.

Enrolments

An Enrolment is a request by a Provider for its Endpoint or System to be enrolled under an API Service or Topic respectively. There are two kinds of Enrolments:

• Enroll Endpoint to API: implies that the Provider's Endpoint has committed to providing information listed in the scope of that particular OAuth API that the it has enrolled to.
• Enroll System to Topic: implies that the Provider's System has committed to sending information to consumers subscribed to this Topic.

Hence, each API can have many Endpoints from different Providers that provide information when it is called. Similarly, each Topic can have many Systems from different Providers that can send information to it to forward to listening Consumers. The diagrams below illustrate this concept.

Subscriptions

A Subscription is a request by a Consumer for its Client Application(s) and Webhook(s) to subscribe to APIs and Topics respectively under a Directory. A Consumer will subscribe at a Directory level and can choose which API(s) and/or Topic(s) they would like to subscribe to. This means that a Consumer need not subscribe to all APIs and Topics under the chosen Directory.

• Client Application Subscribe to API: implies that the Client Application would like to have permission to send a request to the API to get data.
• Consumer Webhook Subscribe to Topic: implies that the Webhook would like to receive data from a Topic when any enrolled Provider System sends data.

Because each API and Topic may have numerous Providers, each Provider enrolled under an API/Topic that is being subscribed to will receive separate Subscription Requests for them to approve or reject.

A Subscription Request is hence an individual request (a subset of the full Subscription) sent to Providers enrolled under an API or Topic to seek their approval when a Consumer would like to subscribe to the API/Topic they are providing to.

The diagram below illustrates the relationship between a Subscription and Subscription Requests.

In the diagram above, a Consumer with Client Application B and Webhook C creates a Subscription request to the API with Endpoint A enrolled and a Topic with System Z enrolled. Because there are 2 Providers, SGDex created 2 separate Subscription Requests to each Provider for their approval to the Subscription.

This section illustrates how you can route data in your data exchange from Providers to Consumers. In the previous sections, we focused on configuring the routing rules needed in your data exchange. In this section, we focus on the actual flow of data.

Before you can route data along a specific path (e.g. a Topic) in a data exchange, you must have permission to do so. This permission is granted to Providers and Consumers via the approval of their Enrolment and Subscription requests to that specific path. With no prior approvals, Providers and Consumers are unable to send or receive data from that path in the data exchange.

In routing, there are mainly 2 flows:

1. Retrieval of Data

   • Synchronous Retrieval

   • Asynchronous Retrieval

2. Providing of Data

The following sections will illustrate how these flows work in the data exchange.

Retrieval of Data (PULL)

This section illustrates how Consumer Client Applications can retrieve data from Provider Endpoints via an API.

When a Consumer Client Application wants to retrieve data, SGDex calls your pre-defined API in Organising and Configuring Your Data Exchange, which will then fetch data from relevant Provider Endpoints previously enrolled to this API.

Consumer Client Applications can either retrieve data synchronously or asynchronously.

Synchronous Retrieval

Once a request for synchronous retrieval is made, SGDex will fetch data from relevant Provider Endpoints enrolled to this API, consolidate all these data and return them all in one payload to the caller.

More details about the required parameters and return types can be found in ROUTING section. The diagram below illustrates how a Synchronous Retrieval is done.

Asynchronous Retrieval

Once a request for asynchronous retrieval is made, SGDex will first return an acknowledgement immediately. SGDex will then fetch data from relevant Provider Endpoints enrolled to this API, and send the Provider Endpoints' responses individually to the caller's pre-defined webhook.

More details about the required parameters and return types can be found in ROUTING section. The diagram below illustrates how an Asynchronous Retrieval is done.

Providing of Data (PUSH)

This section illustrates how Provider Systems can send data to Consumer Webhooks via an API. When a Provider System wants to send data, SGDex calls your pre-defined Topic in Organising and Configuring Your Data Exchange, which will then send this data to relevant Consumer Webhooks previously subscribed to this Topic.

More details about the required parameters an return types can be found in ROUTING section. The diagram below illustrates how data is sent to Consumer Webhooks.

Delivery Receipts

A unique feature of Providing Data is the presence of delivery receipts. When a Provider System sends data to a Topic with a list of Consumer Webhooks, SGDex will fire the information to each Webhooks individually, and send a Delivery Receipt to a pre-specified Provider Webhook to inform Provider Systems on the status of the deliveries.

Provider Systems can even poll another API to query the status of delivery for their request to send data if they prefer not to receive delivery receipts from their Provider Webhook.

SGDex API gateway supports accessing of APIs via HTTP over TLS (Transport Layer Security) version 1.2 standards.

Supported Cipher Suites

The list of supported Cipher Suites are as follows:

• TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
• TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
• TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
• TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

Data Exchange clients (e.g. SGTraDex) must authenticate to SGDex for every request. SGDex uses JWT (specified in RFC 7523) provided in the Authorization header as a bearer token (specified in RFC 6750) for client authentication.

JWT format

Briefly, an unencrypted, signed JWT consists of three parts:

1. The header;
2. The body or payload; and
3. A signature of the payload.

The header may include information about the key and algorithm used to sign the payload. This is needed unless the receiver has obtained this information through other means. As an example, a JWT used for client authentication may have a header and payload like this:

{
  "alg": "ES256",
  "typ": "JWT",
  "kid": "7229075d-972f-4b21-8a0c-38db3a7f2a98"
}

The associated payload may look like this:

{
  "aud": "https://api.sgdex.gov.sg",
  "iss": "client-one",
  "sub": "client-one",
  "nbf": 1535806905,
  "exp": 1535810505,
  "iat": 1535806905,
  "jti": "id123456"
}

JWT parameters include the following:

	Parameter Name	Parameter Value
REQUIRED	aud	SGDex domain e.g. https://api.staging-sgdex.gov.sg for staging environment
REQUIRED	iss	application_id issued by SGDex during onboarding
REQUIRED	sub	application_id issued by SGDex during onboarding
REQUIRED	exp	expiration time of token in epoch format - maximum of 5 minutes from time JWT is generated
REQUIRED	iat	issued at - the time at which the JWT was issued
OPTIONAL	nbf	not before - the time before which the token MUST NOT be accepted for processing
OPTIONAL	jti	JWT ID - unique identifier for the token

Signature

• A JWT must be digitally signed using a private key in asymmetric cryptography (e.g. RS256).
• A client using the authentication method has to register its public key to SGDex in advance so that the SGDex can verify the token.

Sending JWT in Request

The JWT sent to the SGDex should be a Bearer token in the Authorization header, as described in RFC 6750. A sample request is shown below:

GET /{dex}/{usecase}/{api} HTTP/1.1
Host: stg.api.sgdex.gov.sg
Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJodHRwczovL3N0Zy5hcGkuc2dkZXguZ292LnNnIiwiaXNzIjoiY2xpZW50LW9uZSIsInN1YiI6ImNsaWVudC1vbmUiLCJuYmYiOjE1MzU4MDY5MDUsImV4cCI6MTUzNTgxMDUwNSwiaWF0IjoxNTM1ODA2OTA1LCJqdGkiOiJpZDEyMzQ1NiJ9.1ba2xgaRfxiu18SBPauA4ibe21uqI1lymtFoYXrFpMysQVADei98guL4QKHqgwD6UwHBOkC_L5W6TR19g1fuoQ

Partner's application is required to generate DPoP Proof JWT to be attached to server-to-server resource calls to prove the legit possession of the access token. (Refer to https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop). The token is signed by partner's ephemeral private signing key, which the partner's public signing key had been used in the token call and "embedded" into the access token provided. Below is a sample of the JWT header and payload of a DPoP token:

  {
    "typ": "dpop+jwt",
    "alg": "ES256",
    "jwk": {
      "kty": "EC",
      "kid": "CRx5jixF8ZLRpxpqguxCwiq0g6b-ACHfQQJT7uiAkio",
      "alg": "ES256",
      "crv": "P-256",
      "x": "mxVK8wvCaQ8iUJ4AyZr1oK1_ceL_27kgTPISNEcChm4",
      "y": "0P-81zpWvcy6YAPSiV_K4h94wdEdk-RwrhbTL0fkeyc"
    }
  }
  . {
    "jti": "dfgsrtsDFBBgbsB230afktmdFGdgegemmet",
    "htu": "https://api.sgdex.gov.sg/sgfindex/api/fpdata/08939d6c-11c0-4bc9-b2cd-f5fd14369521",
    "htm": "GET",
    "iat": 1645757787,
    "exp": 1645757907,
    "ath": "RyPeyISsEqdR1lsZBv80o0A8eF1Kvxdm_uf1hnLRf9M"
  }

• {typ} Type - Type (Header), value "dpop+jwt"

• {alg} Algorithm (Header) - digital signature algorithm identifier as per RFC7518 (Refer to https://datatracker.ietf.org/doc/html/rfc7518). MUST NOT be none or an identifier for a symmetric algorithm (MAC).

• {jwk} JSON Web Key (Header) - public key chosen by the client. MUST NOT contain the private key.

  • {kty} - The family of cryptographic algorithms used with the key

  • {kid} - The unique identifier for the key

  • {alg} - The specific cryptographic algorithm used with the key

  • {crv} - The crv member identifies the cryptographic curve used with the key

  • {x} - The x member contains the x coordinate for the elliptic curve point

  • {y} - The y member contains the y coordinate for the elliptic curve point

• {jti} JWT ID (Payload) - unique identifier

• {htu} HTTP URL (Payload) - HTTP URI used for the request, without query (?) and fragment parts (#)

• {htm} HTTP Method (Payload) - HTTP method for the request to which the JWT is attached

• {iat} Issued At (Payload) - current timestamp

• {exp} Expiry (Payload) - expiry timestamp

• {ath} Access token hash (Payload) - The base64url encoded SHA-256 hash of the ASCII encoding of the associated access token's value

Sample Code in NodeJS that generates the DPoP token

  // function to generate the base64url encoded SHA-256 hash of the ASCII encoding of the accesstoken
  function generateAth(accessToken) {
    let sha256AccessToken =  crypto.createHash('sha256').update(accessToken).digest();
    let base64URLEncodedHash = sha256AccessToken.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
    return base64URLEncodedHash;
  };
  
  // generates DPoP Proof JWT headers for calling **fpdata** API
  async function generateDpopProof  (url, method, sessionPopKeyPair, ath) {
    try {
      let now = Math.floor((Date.now() / 1000));
      let payload = {
        "htu": url,
        "htm": method,
        "jti": generateRandomString(40),
        "iat": now,
        "exp": now + 120,
      };

      // required only for /fpdata resource call
      if(ath)payload.ath = ath; 

      let privateKey = await jose.JWK.asKey(sessionPopKeyPair.privateKey, "pem");
      let jwk = (await jose.JWK.asKey(sessionPopKeyPair.publicKey, "pem")).toJSON(true);;
      jwk.alg = "ES256";
      let jwtToken = await jose.JWS.createSign({ "format": 'compact', "fields": { "typ": 'dpop+jwt', "jwk": jwk } }, { "key": privateKey, "reference": false }).update(JSON.stringify(payload)).final();
      return jwtToken;
    } catch (error) {
      logger.error("generateDpop error", error);
      throw constant.ERROR_GENERATE_DPOP;
    }
  };

The Partner's application is required to generate client assertions to be attached to server-to-server calls to prove authenticity (Refer to https://datatracker.ietf.org/doc/html/rfc7521). The partner's private key signs the assertion metadata, and SGDex will use the partner's onboarded JWKS endpoint to obtain the public key for verification. Below is a sample of the JWT header and payload of the client assertion:

  {
    "typ": "JWT",
    "alg": "ES256",
    "kid": "x0zDLIC9yNRIXu3gW8nTQDOMNe7sKMAjQnZj3AWTW2U",
  } . {
    "sub": "STG2-APIM-SELF-TEST",
    "jti": "jNDZuyLw66gkTjmCNMawzrTJNlhS8wdjpU0DHTzo",
    "aud": "https://api.staging-sgdex.gov.sg/sgfindex/fpdata/77e0ff15-88be-474a-84ab-5b24ac2fb9d6",
    "iss": "STG2-APIM-SELF-TEST",
    "iat": 1662365106,
    "exp": 1662365406,
    "htm": "POST"
  }

Description of JWT header attributes:

• {typ} Type - value "JWT"
• {alg} Algorithm - value "ES256"
• {kid} Key ID - The unique identifier for the key.

Description of JWT payload attributes:

• {sub} Subject - client_id issued by SGDex upon onboarding
• {jti} JWT ID - random unique identifier
• {aud} Audience - URL that partner's application is calling
• {iss} Issuer - client_id issued by SGDex upon onboarding
• {iat} Issued At (Payload) - current timestamp
• {exp} Expiry (Payload) - expiry timestamp
• {htm} HTTP Method (Payload) - HTTP method for the request to which the JWT is attached

SGDex uses standard HTTP response codes to indicate the success or failure of each API request. For successful requests, our APIs return 2XX codes. Generally, our HTTP error codes have the following implication:

• 4XX: Indicates error in the request format, parameters or that your requested items are not found
• 5XX: Indicates Server errors

The general format of our error responses are as follows:

{
    "code": "integer (int32)",
    "message": "string"
}

List of HTTP Response Codes:

Code	Possible Reasons
400 Bad Request	Invalid parameters (missing, additional or wrongly formatted)
401 Unauthorised	The client_id/system_id mismatched with iss field in JWT token
403 Forbidden	No permission to modify an item
404 Not Found	Invalid Path Parameters ID given was not found
500 Server Error	Unexpected Error

Refer to the individual API definitions for the error codes you might encounter for each API.

Staging Environment

This environment allows you to test your application with production-level security requirements, without needing to test your application directly in production.

The following are some essential information that you might need to test your applications with:

• Domain Name: https://api.staging-sgdex.gov.sg/

Production Environment

The environment where your application will be integrated with SGDex in production.

The following are some essential information that you might need to test your applications with:

• Domain Name: https://api.sgdex.gov.sg/

This section mentions all information related to versioning.

• 1.2.0-release (27 Jun 2024)

  • Removed organisation concept
  • Removed dex path parameter from application, endpoint, jwks endpoint, webhook. organisation and participant API.
  • Updated update enrolment API to support the update of processing_task array
  • Added create authorisation request API

• 1.1.0-release (6 Nov 2023)

  • Removed usecase api service concept
  • Removed directory concept
  • API/Topic softlink to usecase only
  • Mandate iat field as mandatory in generated signed JWT
  • Added new resource api
  • Added new supported security mechanism (APIkey) for endpoint

• 1.0.0-release (20 Jun 2022)

  • Added new scope field to routing api - Retrieving Data
  • Added input format and validation pattern

• 0.1.1 (13 Jan 2022)

  • Added SGTraDex helper API, JWKS API

• 0.1.0 (12 August 2021)

  • Initial Draft including APIs for pull and push data

Releases

SGDex's RESTful API adopts Semantic Versioning 2.0.0 for releases with the following format:

The table below lists the possible changes to the release version numbers and what they imply.

{MAJOR} increments	{MINOR} increments	{PATCH} increments
Introduces incompatible API changes with the previous {MAJOR} version	Introduces new functionalities or information that are backward compatible	Introduces bug fixes and remains backward compatible
e.g. v1.2.1 --> v2.0.0	e.g. v1.2.1 --> v1.3.0	e.g. v1.2.1 --> v1.2.2

Despite backward compatibility provided in {MINOR} and {PATCH} releases, developers should still ensure that their existing implementations are not disrupted as a result of these new releases.

Pre-releases/Drafts

Pre-release or draft versions, when provided, are denoted by an appended hypen- with a series of separate identifiers {LABEL}-{VERSION} following the{PATCH} number.

Such releases are unstable and may not provide the intended compatibility with the specification in draft status.

Please contact the SGDex team at support@sgdex.gov.sg for support.