GraphQL

GraphQL is available on all DEPLOY Geth Nodes.

Introduction

Ethereum's smart contract ecosystem and fast block times can yield lots of data very quickly. Querying Ethereum chain data using JSON-RPC or REST API endpoints results in having to make multiple requests in order to get the full picture of a block or an address' state on the blockchain. Since each of these requests are simple queries selecting a single resource or set of resources using an identifier, applications built on these APIs often incur high request-per-second rates as it may take many requests to get the full picture. For example, users expect their wallet applications to display their token balances across many smart contracts, checking balances of an address on multiple token contracts would require multiple calls to an Ethereum node when using REST or JSON-RPC APIs. If these request are made over the network they may also induce a high latency cost, or if they are made by a mobile device, the computation required to merge the responses could be resource intensive, causing the application to appear slow or bandwidth intensive.

GraphQL is a technology first pioneered by Facebook in order to make the mobile experience of their properties more efficient and responsive. Instead of making multiple requests to a REST API for lists of items, then additional individual requests to fetch the details of each item, GraphQL allows us to write queries that are evaluated by the API server on our behalf and then returned exactly in the shape we expect. In the context of a social network, a single GraphQL query may fetch a user's friends list but only the relevant information to display a list like their profile picture, name, and if they're available to chat; all in one simple query without the overhead of also having to receive additional information like each friend's mobile number, last status update, location information, etc.

The same technology can be applied to Ethereum's depth of information generated with every new block. Using the GraphQL middleware you can retrieve specific subsets of information about blocks within a given range or with a certain attribute without having to make multiple API queries and without receiving more data than you need. Instead of receiving the entire data contents of a series of transactions, you can choose to select only the to, from, and amount attributes and the GraphQL API service will resolve your query and only return the information you need to see. (See below for an example.)

GraphQL endpoints are also more bandwidth efficient for mobile users or metered connections. Using DEPLOY's API servers running the GraphQL middleware uses our dedicated equipment to perform your queries as fast as possible without sending excess data or causing the client to make multiple requests.

With the GraphQL middleware your application can get exactly the data it needs in one API request without the computational overhead.

Installing

The GraphQL middleware is available to Go-Ethereum (Geth) based Ethereum nodes under the shared node and owned node subscriptions.

Shared Node

All Geth shared node subscriptions come with the GraphQL middleware preinstalled. Simply navigate to My Node -> Middleware -> GraphQL and click View to view your connection information.

Owned Node

After subscribing to a Geth based owned node, simply navigate to My Node -> Middleware -> GraphQL, click View to review detailed information about the middleware, and click Install GraphQL to install the middleware on your owned node. After the installation is completed, navigate to the GraphQL middleware page to view your connection information.

Connecting

The GraphQL endpoint will follow the same scheme for both shared node subscriptions and owned node subscriptions. The endpoint will be https://<your node's host>/graphql. This endpoint will be your target when sending HTTP POST requests with your GraphQL query.

For example, sending an HTTP POST request with the following payload to https://gethmainnet12345.nodes.deploy.radar.tech/graphql would return the from address, block number, block timestamp, and transaction hash from all transactions within blocks 8530400 to 8530401 on the Ethereum mainnet.

{
logs(filter: { fromBlock: 8530400, toBlock: 8530401 }) {
transaction {
hash
from {
address
}
block {
number
timestamp
}
}
}
}

Example Usage

If you're building an application that relies on querying information across multiple blocks, addresses, or transactions GraphQL offers the ability to easily join results together into one response. A straightforward query like the example provided above allows a single HTTP request to fetch information about multiple transactions, in a range of blocks, and only return the relevant information without wasting bandwidth. For more GraphQL query examples please see Example Queries.

Querying the same information via a REST or JSON-RPC API would require "N+1" queries, meaning that in order to fetch information about the first twenty transactions in a block you would first have to query the API for the transaction hashes in the block, then once for each transaction hash to get the details of that transaction. The REST API would result in a higher latency to fetch the information needed, and increased computational requirements to merge the data or to handle failed requests. Meanwhile a single GraphQL query can fetch, merge, and filter the resulting data into only the relevant parts without the need for a client side implementation.

GraphQL's ability to allow the client to only request the attributes or fields they are interested in saves bandwidth and makes API responses faster over the wire.

Uninstalling

Shared Node

You cannot uninstall the GraphQL middleware from a shared node subscription since it is included at no extra charge and is a shared resource.

Owned Node

In order to uninstall the GraphQL middleware, you must restore your owned node to default settings. To remove the middleware navigate to My Node -> Middleware -> GraphQL and click Restore Node to Default Settings. Confirm you wish to restore the node to default settings by clicking Restore Node.

See Also