logo
API docs by Redocly

SGBuildex APIs (0.1.2 DRAFT)

Download OpenAPI specification:

APIs for external integrators to call SGBuildex for creation of data exchange.

INTRODUCTION

SGBuildex provides a common set of APIs for integrating with pitstops.

The APIs are divided into the following categories:

  • Data Exchange
  • Utilities

API CATEGORIES

Data Exchange

Data Exchange in SGBuildex happens in an asynchronous fashion.
You can either request for data from another participant (PULL) or send data directly to another participant (PUSH).

Requesting for Data

Requesting Data

When requesting for data, the following are the sequence of events described by the diagram:

  1. Consuming source system sends a PULL request to consuming pitstop (Pitstop A) on SGBuildex.
  2. SGBuildex forwards the call from consuming pitstop to the destination pitstop.
  3. Provider pitstop requests for the data from the provider source system by calling the provider source system with a PROVIDE call. If available, the provider source system will respond with the requested data payload.
  4. SGBuildex encrypts and forwards the encrypted data payload back to the consuming pitstop.
  5. Consuming pitstop calls the consuming source system with a RECEIVE call with the data payload.
  6. Consuming pitstop calls the consuming source system with a NOTIFY call to let the consuming source system know of the success/failure of the PULL request.

Sending Data

Sending Data

When sending data, the following are the sequence of events described by the diagram:

  1. Provider source system calls provider pitstop (Pitstop A) in SGBuildex with a PUSH call containing the data payload.
  2. SGBuildex encrypts and forwards the data payload to the consuming pitstop (Pitstop B).
  3. Consuming pitstop calls the consuming source system with a RECEIVE call with the data payload.
  4. The result of the push is forwarded back to the provider pitstop
  5. Provider pitstop calls the provider source system with a NOTIFY call to let the provider source system know of the success/failure of the PUSH request.

Utilities

SGBuildex provides the following utility APIs:

Ingress Utility APIs

  • Health Check
  • Pitstop Config
  • Upload File(s)
  • File Download

Egress Utility APIs

  • Health Check
  • Notify

INGRESS/EGRESS APIs

To integrate successfully to SGBuildex, there are 2 types of APIs:

  • Ingress APIs: APIs that your system will call SGBuildex
  • Egress APIs: APIs that SGBuildex will call your system
    Note: your system will need to provide these APIs for integration to be successful.

Ingress APIs

Ingress APIs are APIs provided by SGBuildex, and which your system will need to call.

Data Exchange APIs

Data Exchange APIs are used for sending and requesting for data. These are:

API uri Description
PULL /data/pull/{dataElementId} Request to pull data from provider
PUSH /data/push/{dataElementId} Push data to pitstop
STORE /data/store/{dataElementId} Store data element in pitstop for subsequent use
FORWARD data/forward/{dataElementId} Forward data existing in pitstop to another participant

Each of the APIs will take in a dataElementId path parameter to denote the Data Element type of the transaction. The Data Element type will determine the payload and parameters attributes in your request/responses (see specifications in each API for details).

Data Element types are defined based on the use case they are in. Each use case defines the schema for the Data Elements.

Utility APIs

Ingress Utility APIs are additional utility APIs provided by SGBuildex system.

API uri Description
HEALTH /health Health check to see if pitstop is healthy. Will return 200 if pitstop is healthy.
CONFIG /config This will return the list of Data Elements / documents that your pitstop is configured to produce and consume, as well as the recipients that you have consented to share them with.
UPLOAD FILES /files Uploads file(s) to the pitstop Uploads the files in multipart format to the pitstop and return references to each of them for use to send the data.
DOWNLOAD FILE /files/{file_id} Downloads the binary file with the corresponding ID from the pitstop.

Egress APIs

Egress APIs are APIs which SGBuildex pitstop will call your system.
Note: your system will need to provide these APIs for integration to be successful.

Data Exchange APIs

Data Exchange APIs are used for sending and receiving for data.

API uri Description
PROVIDE /data/provide/{dataElementId} Request for source system to provide data
RECEIVE /data/receive/{dataElementId} Receive data from pitstop
NOTIFY /notify Notification from pitstop on the success/failure of previous request

Each of the APIs will take in a dataElementId path parameter to denote the Data Element type of the transaction. The Data Element type will determine the payload and parameters attributes in your request/responses (see specifications in each API for details).

Data Element types are defined based on the use case they are in. Each use case defines the schema for the Data Elements.

Utility APIs

Egress Utility APIs are additional utility APIs which SGBuildex pitstop will call your system.

API uri Description
HEALTH /health Pitstop will call source system to check if source system is healthy.
NOTIFY /notify Notification from pitstop on the success/failure of previous request

SCHEMAS

The payload and parameters attributes in the various data exchange APIs are available in the payload sections of the individual APIs. However, if you need to refer to them in detail, see below:

CLICK HERE for the payload and parameters schemas for the various use cases.

VERSIONING

This section mentions all information related to versioning.

Releases and Compatibility

Releases

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

{MAJOR}.{MINOR}.{PATCH}

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.

{MAJOR}.{MINOR}.{PATCH}-{LABEl}-{VERSION}

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

Release Notes

0.0.1 (DRAFT 2 October 2023)

  • new draft specs for SGBuildex

0.1.0 (DRAFT 5 Mar 2025)

  • combined schemas into main specifications page for easy reference.

0.1.1 (DRAFT 5 Mar 2025)

  • remove simulate for now as it is not in use.

0.1.2 (DRAFT 6 Mar 2025)

  • cleanup references

INGRESS Utilities

Utility APIs

Pitstop Config

This will return the list of documents that your pitstop is configured to produce and consume, as well as the recipients that you have consented to share them with.

Responses

Response samples

Content type
application/json
{
  • "identity": {
    },
  • "produces": [
    ],
  • "consumes": [
    ],
  • "contributes": [
    ]
}

Health Check

For the Participant / Pitstop to monitor whether their Pitstop / Source System is operational or not. Should return a 200 if it is working.
Note:

  • For INGRESS (i.e. hosted by Pitstop), returns 200 if pitstop is healthy.
  • For EGRESS (i.e. hosted by source system), pitstop will call to check if source system is healthy.

    • Responses

    Upload File(s)

    Uploads file(s) to the pitstop Uploads the files in multipart format to the pitstop and return references to each of them for use to send the data.

    Request Body schema: multipart/form-data
    object

    Any key with the file as the value will all be read

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    File Download

    Downloads the binary file with the corresponding ID from the pitstop.

    path Parameters
    file_id
    required
    string

    Responses

    Response samples

    Content type
    application/json
    {
    • "timestamp": "2019-08-24T14:15:22Z",
    • "data": "string"
    }

    INGRESS Data Exchange

    Data Exchange related APIs

    PUSH DATA

    Add a document of specified Data Element type into an existing data package to participants.
    Created document_id will be returned in the response body.

    path Parameters
    dataElementId
    required
    string
    Enum: "lift_datahub" "piling_installation_record" "ultimate_load_test" "working_load_test" "concrete_cube_test" "concrete_cube_test_laboratory" "steel_element_test" "steel_rebar_test" "site_progress" "qualified_person_site_supervisor_attendance"

    Data Element ID of the data element to be sent

    Request Body schema: application/json
    required
    Array of Lift Datahub (object) or Piling Installation Record (object) or Ultimate Load Test (object) or Working Load Test (object) or Concrete Cube Test (Contractor) (object) or Concrete Cube Test (Laboratory) (object) or Steel Element Test (object) or Steel Rebar Test (object) or Site Progress (object) or Qualified Person and Site Supervisor Attendance (object) (Data Element JSON)

    JSON payload of data element documents.
    Must be one of the defined dataElementId types as per below.
    See the examples.
    Note currently only supports 1 payload in the array

    requestId
    string

    Optional field. Include if you know the requestId for your resource.
    requestId - Unique ID generated for the request

    sourceSystemId
    string (Source System Id)

    Optional field. Own Source System's Id for Notification. Participant can ignore it when flow is anything other than PUSH or PULL.

    required
    Array of objects (participant)
    Array of objects

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "participants": [
      ],
    • "payload": [
      ],
    • "requestId": "string",
    • "on_behalf_of": [
      ],
    • "sourceSystemId": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "timestamp": "2019-08-24T14:15:22Z",
    • "data": {
      }
    }

    STORE DATA

    Store the Data Element in the pitstop for future retrieval

    path Parameters
    dataElementId
    required
    string
    Enum: "lift_datahub" "piling_installation_record" "ultimate_load_test" "working_load_test" "concrete_cube_test" "concrete_cube_test_laboratory" "steel_element_test" "steel_rebar_test" "site_progress" "qualified_person_site_supervisor_attendance"

    ID of the data element to be stored

    Request Body schema: application/json
    required
    Array of Lift Datahub (object) or Piling Installation Record (object) or Ultimate Load Test (object) or Working Load Test (object) or Concrete Cube Test (Contractor) (object) or Concrete Cube Test (Laboratory) (object) or Steel Element Test (object) or Steel Rebar Test (object) or Site Progress (object) or Qualified Person and Site Supervisor Attendance (object) (Data Element JSON)

    JSON payload of data element documents.
    Must be one of the defined dataElementId types as per below.
    See the examples.
    Note currently only supports 1 payload in the array

    requestId
    string

    Optional field. Include if you know the requestId for your resource.
    requestId - Unique ID generated for the request

    sourceSystemId
    string (Source System Id)

    Optional field. Own Source System's Id for Notification. Participant can ignore it when flow is anything other than PUSH or PULL.

    required
    Array of objects (participant)
    Array of objects

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "participants": [
      ],
    • "payload": [
      ],
    • "requestId": "string",
    • "on_behalf_of": [
      ],
    • "sourceSystemId": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "data": [
      ]
    }

    EGRESS Utilities

    Utility APIs

    Health Check

    For the Participant / Pitstop to monitor whether their Pitstop / Source System is operational or not. Should return a 200 if it is working.
    Note:

  • For INGRESS (i.e. hosted by Pitstop), returns 200 if pitstop is healthy.
  • For EGRESS (i.e. hosted by source system), pitstop will call to check if source system is healthy.

    • Responses

    Notify Changes

    This endpoint will be used to notify participant with status message as well as about the config changes. This will return the notification of the message and config changes.

    Request Body schema: application/json
    timestamp
    required
    string (Timestamp)

    Date and Time of the request sent/received

    notify_message
    required
    string (Notify Message)
    Enum: "REFRESH_CONFIG" "PUSH_FAIL" "PUSH_SUCCESS" "PULL_FAIL"

    REFRESH_CONFIG | PUSH_FAIL | PULL_FAIL | PUSH_SUCCESS

    notify_message_stage
    string or null (Notify Message Stage)
    Enum: "PITSTOP" "SOURCE"

    PITSTOP | SOURCE

    request_id
    string or null (Request Id)

    Original request from source or pitstop from which the request is originated

    error_code
    number or null (Error Code)

    Internal error code from DEX Pitstop

    error_message
    string or null (Error Mesage)

    Internal error message from DEX Pitstop

    (Source System Error (string or null)) or (Source System Error (object or null)) (Source System Error)

    This field captures and relays the exact error message returned by the API consumer system. No additional processing or classification is performed on this field, ensuring that the error information is relayed exactly as received from the API consumer system.

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "timestamp": "2021-05-11T03:35:38.464Z",
    • "notify_message": "PUSH_FAIL",
    • "request_id": "d4002d09-f0d7-4258-8428-0032fd8d2f52",
    • "error_code": 500,
    • "error_message": "Consumer source API error",
    • "source_system_error": { }
    }

    Response samples

    Content type
    application/json
    {
    • "timestamp": "string"
    }

    EGRESS Data Exchange

    Data Exchange related APIs

    Notify Changes

    This endpoint will be used to notify participant with status message as well as about the config changes. This will return the notification of the message and config changes.

    Request Body schema: application/json
    timestamp
    required
    string (Timestamp)

    Date and Time of the request sent/received

    notify_message
    required
    string (Notify Message)
    Enum: "REFRESH_CONFIG" "PUSH_FAIL" "PUSH_SUCCESS" "PULL_FAIL"

    REFRESH_CONFIG | PUSH_FAIL | PULL_FAIL | PUSH_SUCCESS

    notify_message_stage
    string or null (Notify Message Stage)
    Enum: "PITSTOP" "SOURCE"

    PITSTOP | SOURCE

    request_id
    string or null (Request Id)

    Original request from source or pitstop from which the request is originated

    error_code
    number or null (Error Code)

    Internal error code from DEX Pitstop

    error_message
    string or null (Error Mesage)

    Internal error message from DEX Pitstop

    (Source System Error (string or null)) or (Source System Error (object or null)) (Source System Error)

    This field captures and relays the exact error message returned by the API consumer system. No additional processing or classification is performed on this field, ensuring that the error information is relayed exactly as received from the API consumer system.

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "timestamp": "2021-05-11T03:35:38.464Z",
    • "notify_message": "PUSH_FAIL",
    • "request_id": "d4002d09-f0d7-4258-8428-0032fd8d2f52",
    • "error_code": 500,
    • "error_message": "Consumer source API error",
    • "source_system_error": { }
    }

    Response samples

    Content type
    application/json
    {
    • "timestamp": "string"
    }

    RECEIVE DATA

    Add/Update Document (Data Element) to an existing process.

    path Parameters
    dataElementId
    required
    string
    Enum: "lift_datahub" "piling_installation_record" "ultimate_load_test" "working_load_test" "concrete_cube_test" "concrete_cube_test_laboratory" "steel_element_test" "steel_rebar_test" "site_progress" "qualified_person_site_supervisor_attendance"

    ID of the data element to be sent

    Request Body schema: application/json
    required
    Array of Lift Datahub (object) or Piling Installation Record (object) or Ultimate Load Test (object) or Working Load Test (object) or Concrete Cube Test (Contractor) (object) or Steel Element Test (object) or Steel Rebar Test (object) or Site Progress (object) or Qualified Person and Site Supervisor Attendance (object) (Data Element JSON)

    JSON payload of data element documents.
    Must be one of the defined dataElementId types as per below.
    See the examples.
    Note currently only supports 1 payload in the array

    requestId
    string

    Optional field. Include if you know the requestId for your resource.
    requestId - Unique ID generated for the request

    sourceSystemId
    string (Source System Id)

    Optional field. Own Source System's Id for Notification. Participant can ignore it when flow is anything other than PUSH or PULL.

    required
    Array of objects (participantFrom)
    Array of objects

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "participants": [
      ],
    • "payload": [
      ],
    • "requestId": "string",
    • "on_behalf_of": [
      ],
    • "sourceSystemId": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "timestamp": "2019-08-24T14:15:22Z",
    • "data": {
      }
    }