Overview

The Dapi Connect Server (DCS) handles communication between the SDK client and the Dapi API . It is run as a Docker container as part of your backend and configured through arguments provided at start time.

In a nutshell it will:

• Receive a request from SDK client
• Attach appSecret and accessToken (if needed)
• Forward the request to the Dapi API
• Forward responses from the Dapi API to the SDK client

Additional Features

1. Webhooks

You can receive copies of all responses sent to the DCS by providing an HTTP endpoint at start up.

This endpoint will serve as your webhook URL.

Use this feature at your discretion, be it to run analyrics usage or further data processing (e.g. checking failure rate of user calls).

📘

Note

This is an optional feature and you are completely free to disable it for your application.

2. Token Exchange

Use the DCS to handle token exchange after user login.
It will store all Access Tokens on your backend via endpoints on the provided webhook URL.

A bird's eye view of the workflow:

• DCS receives a call from the SDK client
• DCS calls a specific endpoint (detailed below) on your webhook URL to retrieve a previously stored token
• DCS attaches specific access token to the request and sends it to the Dapi API

Since the DCS relies on some REST endpoints, you are free to store the tokens as you see fit in your existing backend storage framework.

📘

Note

Access Tokens are very sensitive and must be stored securely. Ensure that your storage of choice has a proper firewall in place and is inaccessible from the public internet.

Server Setup

The DCS is a Docker image that runs with startup parameters. Use the provided setup-server.sh to help with setting up your server.

This will:

1. Install Docker
2. Pull the latest DCS image from Docker Hub
3. Run the DCS

Run this script as follows:

./setup-server.sh webhookUrl appSecret [listenAddr="0.0.0.0:4561"] [sendResponses=false] [compress=false] [replicas=2] [allowCors=false] [includeStatus=false] [appKey='']

Parameters

An actual usage might looks like this:

./setup-server.sh https://the.backend.com a26ba5047a16f8bba99f11253c92.... 1.2.3.4:7258 true true 3

With this, Docker will be installed and 3 copies (containers) of the server will be started with the provided parameters. These replicas will be load balanced by Docker. In the unlikely case of a crash, Docker will attempt to restart them automatically.

Server Endpoints

A list of all endpoints on the DCS that be called by your backend

Endpoint /Health

GET /Health

Expected Output

Status Code: 200

• This endpoint will respond with 200 (and no body) once the server is up and ready to accept requests.

Webhook Requirements

🚧

Warning

Any deviation from expected outputs (e.g. status code not 2xx or no access token returned) will be considered a failure by the DCS.

📘

Note

All URLs are relative to the webhook URL you provided at start up

The webhook must support the following endpoints:

Endpoint /Ping

GET /Ping

Expected Output

Status Code: 200

• Called at server startup
• The server will shut down if it fails to contact the /Ping endpoint at startup
• A failure to connect to this endpoint is a result of incorrect server configuration or firewall setting

Endpoint /StoreAccessToken

POST /StoreAccessToken

Body

{
  "id": "abcd1234",
  "accessToken": "efgh5678=="
}

Expected Output

Status Code: 200

📘

Note

Store the mapping between id and accessToken. Later calls will require the id to return the accessToken

Endpoint /GetAccessToken

GET /GetAccessToken

Query Parameter

/GetAccessToken?id=abcd1234

Expected Output

Status Code: 200
Body

{ 
  "accessToken": "efgh5678==" 
}

Endpoint /ApiResponse

POST /ApiResponse

• Called only if you have sendResponses enabled

• Has a body that contains responses returned from the Dapi API in JSON format

• Contains a header called Dapi-Url which holds the request URL that produced this response from the API.

  Some example requests that will be sent to this endpoint:

Headers:
  "Dapi-Url": "/v1/data/accounts/get"

Body:
  {
    "jobID": "83515136-9146-523a-9936-3229d51fd49d",
    "status": "done",
    "success": true,
    "accounts": [
      {
        "iban": "GB33BAEDB20201555555893",
        "number": "0201555555893",
        "currency": "AED",
        "type": "savings",
        "name": "Extra Saver Savings Account",
        "isFavourite": false,
        "id": "JRLLZ61yD60bACpJwMrQDUABKwtVH2nNs705L/kjiGk29aFpjyLqInaTZg4FG6BytYoToEyJqjbcFgOQq44m4g=="
      }
    ]
  }

Headers:
  "Dapi-Url": "/v1/data/balance/get"

Body:
  {
    "jobID": "83515136-9146-523a-9936-3229d51fd49d",
    "success": true,
    "status": "done",
    "balance": {
      "amount": 1072.05,
      "currency": "AED",
      "accountNumber": "106666666001"
    }
  }

Headers:
  "Dapi-Url": "/v1/payment/transfer/create"

Body:
  {
    "success": true,
    "status": "error",
    "message": "Invalid senderID"
  }

📘

Note

DCS uses very low memory when idle (less than 20MB) and can therefore be places on the smallest VM you have (e.g. 1 CPU 1 GB RAM).

DCS is completely stateless and can therefore be scaled horizontally by running several DCMs behind a load balancer.