The Enhanced API Service

Our API Service allows you to access managed shared nodes so that you can forget about infrastructure and start developing immediately.

Creating your own API App

Registering and getting access to the API Service only takes a few minutes - we've designed the process to be as easy as possible.

Apps are containers for your set of API keys, dashboards, and analytics all organised in one place within your OnFinality workspace. You can create, independently manage, and view dashboards for multiple API apps, for example one for “Wallet backend” and other for “Wallet iOS staging”. This enables you to analyse separate analytics for each application to better understand your users.

Login to OnFinality

First, go to app.onfinality.io (opens new window) to create an account in OnFinality or log on using your existing account if you already have one.

Once you're in, go to to the API Service page and press Create App to Start

Enter your App’s name and select the Environment. The Environment lets your workspace know whether this is a production critical app or a development or test environment.

Press Create App to get started

Connect to your API App Endpoint

Once you have your API service enabled and running you can now connect to it and start using it in your dApps.

Connect via Command Line

You can connect using websocket or HTTP to your API endpoint. Your API key can be added as a URL parameter ?apikey=${APIKEY} or in the request header -H 'apikey: ${APIKEY}'

For example, the following CURL command can be used to get the current block height of Polkadot

BASH

curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "rpc_methods"}' 'https://polkadot.api.onfinality.io/rpc?apikey=XXXXX'

Connect via Polkadot JS UI

We're going to use the Polkadot/Substrate Portal to connect to our API service, but these instructions will also work for other similar methods.

Head to PolkadotJS UI (opens new window), and then to the Explorer tab under Network, and on the top of your screen click on the Polkadot Icon.

This will open the Network switcher which will allow you to select the network that you connect to. You can add your OnFinality API service endpoint to the Development section by pasting the websocket connection URL into the custom endpoint field and clicking on the save icon.

Congratulations, you're now connected and can start making calls with the Polkadot/Substrate UI App. We can't wait to see that you start building!

A Tour of your API App

The API Service overview page currently has three sections; Today’s Requests indicator, a history of your workspace’s requests, and a list of your active apps.

Today’s Request Indicator

Our API Service plans are billed based on the number of requests per day across all apps. As shown above, our free tier currently includes 500,000 requests a day across all networks that reset every 24 hours. This section clearly shows how many requests you have consumed in the progress bar and when your daily usage count resets.

To upgrade your plan and receive a higher daily limit please contact sales@onfinality.io

Total Requests graph

The Total Requests graph lets you see your historical API usage. Hover over a data point to see the breakdown by app.

It will also highlight when your daily request limit was reached in previous days.

Apps List

The Apps List shows all active apps and their share of today’s API usage. The App’s Environment lets you know whether it is a production critical app or a dev/test environment.

App Dashboard

Click into an App in your Apps List to see its Dashboard. Here, you can view usage insights, manage the App’s API key, and access the integration urls for each network.

Integrate with Network APIs

For each network, we provide you with two endpoints, an HTTPS and a Websocket connection. Select from your most used “Focused Networks” or press Show All Networks to integrate with a new network

After selecting a network its integration URLs will be displayed. These URLs include your API key which is private and unique to your account. You cannot let anyone know your API key, and you should do as much as possible to protect it and keep it secret as it is directly linked to your billing account.

You can also open the Integration tab to access resources, such as documentation, and an example CURL to run in your terminal

Regenerate API Key

If you believe that your API key is in use by an unauthorized third party, then you can use the Regenerate Key button in Settings the reset it.

API Access Restrictions (Allowlists)

By adding ‘Allow’ listed origins and IP addresses, you can prevent others from using your paid API keys in their own websites or applications. For example, if you run a wallet, you could restrict your private endpoint to only work when accessed from inside your wallet. If you are running an indexer, you could restrict your private endpoint to only work from the IP address of your indexer.

Go to API App > Settings and add an allowed origin or IP address

API Requests

The usage graph shows you the volume of API requests made to your account for the selected Network over the last 24 hours. It provides a breakdown of successful requests and errors.

Hover over a bar to see the error breakdown

‘Service Error’ — An internal error with the OnFinality gateway
‘Node Error’ — When the node is unable to process the request
‘Client Error’ — An invalid request or client formatting error
‘Too Many Requests’ — Indicates that rate limits have been exceeded
‘Unknown Error’ — Indicates that something odd has happened. Contact us for help!

Response Times

The Response Time graph shows the 50th Percentile, 95th Percentile, and Average response times for the selected network.

Drill down to a specific method using the filter to see the response times for that method

Requests by Country

The Requests by Country graph helps you to better understand where in the world your users are.

Your marketing and business development teams will find this useful, as it allows you to identify where your users are and measure the effectiveness of marketing campaigns in certain regions.

It is also helpful in detecting and responding to unusual traffic or misuse of your API Key, see API Access Restrictions above.

See also our privacy policy to understand how we populate this graph while maintaining your user’s privacy https://onfinality.medium.com/how-does-onfinality-deal-with-personal-information-c55b287cd1a7

Methods Summary

The Methods Summary provides valuable insight into how your users are using our API, and in turn your dApp.

Sort by column to highlight the most popular requests or methods which aren’t performing as expected.