Using APIs

Check out this demo, which walks you through using a Dhali linked API:

Each API on Dhali has a unique base endpoint. To access the API, send requests to the base endpoint with extra routes determined by the API's spec. In addition, to fund your service usage you must supply a payment claim (i.e., a Dhali API key). This payment claim is a Base64 encoded JSON object that can be provided either in the HTTP headers or directly embedded as a query parameter. The payment claim takes the following form:

{
    "version": "<a version number>",
    "account": "<Your account classic address>",
    "destination_account": "<Dhali's classic address>",
    "protocol": "<e.g., XRPL.MAINNET>",
    "currency": {"code": "USD", "issuer": "example account", "scale": 6},
    "authorized_to_claim": "<The max amount (measured in *10^(scale)) that this payment claim allows to be extracted from the channel>",
    "signature": "<A cryptographic signature that only 'account' can create>",
    "channel_id": "<The ID of the channel>"
}

Once you have a valid payment claim, you can use the API as described below.

---

REST Request

URL

API request URLs through Dhali take the form:

https://run.api.dhali.io/{uuid}/{other_paths}

Path Parameters

Name	Type	Description
uuid	String	The UUID of the API
other_paths	String	The API provider's route

Supported Methods

Dhali supports all REST methods: GET, POST, PUT, DELETE, PATCH.

Headers

Name	Type	Description
Payment-Claim	String	A Base64 encoded JSON payment claim. Alternatively, you may embed the payment claim via query parameters using Payment-Claim.
...	String	Additional headers required by the API provider.

Query Parameters

• All query strings are forwarded to the linked API.
• To use an embedded payment claim, include a query parameter named Payment-Claim with the Base64 encoded JSON object as its value.

Response

200 OK

The execution was successful. The response will include the following headers:

Name	Type	Description
dhali-latest-request-charge	String	The cost of this request.
...	String	Additional headers returned by the linked API.

The body of the response will be:

{
    <The API's output>
}

402 Payment Error

If the payment claim is invalid, the response will be:

{
    "detail": "<Explanation of why your payment claim was not valid>"
}

---

WebSocket Request

For real-time communication, Dhali now supports WebSocket connections. The WebSocket endpoint uses the same UUID and route structure as REST requests.

WebSocket URL

wss://run.api.dhali.io/{uuid}/{other_paths}

Path Parameters

Name	Type	Description
uuid	String	The UUID of the API
other_paths	String	The API provider's route

Connection Options

• Headers: If supported by your WebSocket client, include the Payment-Claim header as described in the REST section.
• Query Parameters: Alternatively, embed the payment claim in the WebSocket connection URL using the Payment-Claim query parameter.

After connecting, you can send and receive messages in real time according to the API's specification.

---