Migrating to GraphQL
This guide compares JSON-RPC queries to their equivalent GraphQL counterpart. While it is possible to systematically rewrite JSON-RPC queries (for example, iota_getTotalTransactionBlocks) to their GraphQL counterparts using this guide, it is recommended that you revisit your application's query patterns to take full advantage of the flexibility that GraphQL offers in serving queries that touch multiple potentially nested endpoints (for example transactions, balances, coins), and use the following examples to get a flavor of how the two APIs express similar concepts.
For a comprehensive list of all available GraphQL features, consult the reference.
Example 1: Get total transaction blocks
The goal is to get the total number of transaction blocks in the network.
- JSON-RPC
- GraphQL
{
"jsonrpc": "2.0",
"id": 1,
"method": "iota_getTotalTransactionBlocks",
"params": []
}
query {
checkpoint {
networkTotalTransactions
}
}
Example 2: Get a specific transaction block
The goal is to get the transaction block by its digest.
- JSON-RPC
- GraphQL
{
"jsonrpc": "2.0",
"id": 1,
"method": "iota_getTransactionBlock",
"params": [
"Hay2tj3GcDYcE3AMHrej5WDsHGPVAYsegcubixLUvXUF",
{
"showInput": true,
"showRawInput": false,
"showEffects": true,
"showEvents": true,
"showObjectChanges": false,
"showBalanceChanges": false
}
]
}
query {
transactionBlock(digest: "Hay2tj3GcDYcE3AMHrej5WDsHGPVAYsegcubixLUvXUF") {
gasInput {
gasSponsor {
address
}
gasPrice
gasBudget
}
effects {
status
timestamp
checkpoint {
sequenceNumber
}
epoch {
epochId
referenceGasPrice
}
}
}
}
Example 3: Get coin objects owned by an address
The goal is to return all Coin<0x2::iota::IOTA> objects an address owns.
- JSON-RPC
- GraphQL
query {
"jsonrpc": "2.0",
"id": 1,
"method": "iotax_getCoins",
"params": [
"0x5094652429957619e6efa79a404a6714d1126e63f551f4b6c7fb76440f8118c9", //owner
"0x2::iota::IOTA", //coin type
"0xe5c651321915b06c81838c2e370109b554a448a78d3a56220f798398dde66eab", //cursor
3 //limit
]
}
query {
address(address: "0x5094652429957619e6efa79a404a6714d1126e63f551f4b6c7fb76440f8118c9") {
coins(
first: 3,
after: "IAB3ha2PEA4ESRF4UErsJufJEwYpmSbCq7UNpxIHnLhG",
type: "0x2::iota::IOTA"
) {
nodes {
address
}
}
}
}
The cursor is now passed in the after (or before) fields on the connection, and the limit in the first or last fields.
Related links
- GraphQL reference: Auto-generated GraphQL reference for IOTA RPC.
- GraphQL quick-start: Querying IOTA RPC with GraphQL gets you started using GraphQL to query the IOTA RPC for on-chain data.
- GraphQL concepts: GraphQL for IOTA RPC examines the elements of GraphQL that you should know to get the most from the service.