Using APIs

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

To use an API monetised using Dhali, you need two things: the API's endpoint URL and a payment claim (which acts as your API key). The API provider will give you the specific URL to use.

To generate payment claims, either:

1. Manually, using your web3 wallet via pay.dhali.io.
2. Programmatically, using the npm package dhali-js or python package dhali-py.

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.

---