Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update examples on GraphQL page #1367

Merged
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 96 additions & 7 deletions docs/public-networks/how-to/use-besu-api/graphql.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,31 +8,119 @@ tags:

# Use GraphQL over HTTP

GraphQL can reduce the overhead needed for common queries. For example, instead of querying each receipt in a block, GraphQL can get the same result with a single query for the entire block.
GraphQL can reduce the overhead needed for common queries.
For example, instead of querying each receipt in a block, GraphQL can get the same result with a
single query for the entire block.

The [Besu GraphQL schema] describes the GraphQL implementation for Ethereum. Enable the GraphQL service using [command line options](index.md#enable-api-access).
The [Besu GraphQL schema] describes the GraphQL implementation for Ethereum.
Enable the GraphQL service using [command line options](index.md#enable-api-access).

:::note

GraphQL is not supported over WebSocket.

:::

Access the GraphQL endpoint at `http://<HOST>:<PORT>/graphql`. Configure `<HOST>` and `<PORT>` using [`graphql-http-host`](../../reference/cli/options.md#graphql-http-host) and [`graphql-http-port`](../../reference/cli/options.md#graphql-http-port). The default endpoint is `http://127.0.0.1:8547/graphql`.
Access the GraphQL endpoint at `http://<HOST>:<PORT>/graphql`.
Configure `<HOST>` and `<PORT>` using [`graphql-http-host`](../../reference/cli/options.md#graphql-http-host)
and [`graphql-http-port`](../../reference/cli/options.md#graphql-http-port).
The default endpoint is `http://127.0.0.1:8547/graphql`.

## GraphQL requests with cURL

[Hyperledger Besu JSON-RPC API methods](../../reference/api/index.md) with an equivalent [GraphQL](graphql.md) query include a GraphQL request and result in the method example.
[Hyperledger Besu JSON-RPC API methods](../../reference/api/index.md) with an equivalent
[GraphQL](graphql.md) query include a GraphQL request and result in the method example.

The following [`syncing`](../../reference/api/index.md#eth_syncing) request returns data about the synchronization status.
For example, the following request returns the block number:

<!--tabs-->

# Request

```bash
curl -X POST -H "Content-Type: application/json" --data '{ "query": "{block{number}}"}' http://localhost:8547/graphql
```

# Response

```json
{
"data" : {
"block" : {
"number" : "0x281"
}
}
}
```

<!--/tabs-->

The following request returns the gas price:

<!--tabs-->

# Request

```bash
curl -X POST -H "Content-Type: application/json" --data '{ "query": "{gasPrice}"}' http://localhost:8547/graphql
```

# Response

```json
{
"data" : {
"gasPrice" : "0x0"
}
}
```

<!--/tabs-->

The following [`syncing`](../../reference/api/index.md#eth_syncing) request returns data about the
synchronization status:

<!--tabs-->

# Request

```bash
curl -X POST -H "Content-Type: application/json" --data '{ "query": "{syncing{startingBlock currentBlock highestBlock}}"}' http://localhost:8547/graphql
```

# Response

```json
{
"data" : {
"syncing" : {
"startingBlock" : 665,
"currentBlock" : 3190,
"highestBlock" : 26395
}
}
}
```

<!--/tabs-->

:::info note
In some cases, for example, when your node is fully synced, the syncing request returns a `null` response:

```json
{
"data" : {
"syncing" : null
}
}
```
:::

## GraphQL requests with GraphiQL app

The third-party tool, [GraphiQL](https://github.com/skevy/graphiql-app), provides a tabbed interface for editing and testing GraphQL queries and mutations. GraphiQL also provides access to the [Besu GraphQL schema] from within the app.
The third-party tool, [GraphiQL](https://github.com/skevy/graphiql-app), provides a tabbed interface
for editing and testing GraphQL queries and mutations.
GraphiQL also provides access to the [Besu GraphQL schema] from within the app.

![GraphiQL](../../../assets/images/GraphiQL.png)

Expand All @@ -42,7 +130,8 @@ The third-party tool, [GraphiQL](https://github.com/skevy/graphiql-app), provide

:::info

Besu does not execute pending transactions so results from `account`, `call`, and `estimateGas` for Pending do not reflect pending transactions.
Besu does not execute pending transactions so results from `account`, `call`, and `estimateGas` for
Pending do not reflect pending transactions.

:::

Expand Down