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.

Sign up for GitHub

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

Jump to bottom

fix: GraphQL API doc, stale info, broken links #499

Merged
merged 4 commits into from
Jul 19, 2023
Merged

fix: GraphQL API doc, stale info, broken links #499

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
79cc5d6
old doc, stale info, broken links
barriebyron Jul 13, 2023
e27d196
add Coda so the links show in the PR and add the GraphQL API Endpoint…
barriebyron Jul 13, 2023
752ee5c
Update docs/node-developers/graphql-api.mdx
barriebyron Jul 17, 2023
ecc127e
Update docs/node-developers/graphql-api.mdx
barriebyron Jul 17, 2023
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
36 changes: 18 additions & 18 deletions docs/node-developers/graphql-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,17 +19,21 @@ A new version of Mina Docs is coming soon! This page will be rewritten.

:::

The Mina daemon exposes a [GraphQL API](https://graphql.org/) used to request information from and submit commands to a running node. By default, an HTTP server runs on port `3085`, though this may be configured by passing the `-rest-port` flag to the daemon startup command.
The Mina daemon exposes a [GraphQL API](https://graphql.org/) used to request information from and submit commands to a running node.

To use the GraphQL API, connect your GraphQL client to `http://localhost:3085/graphql` or open in your browser to utilize the [GraphiQL IDE](https://github.com/graphql/graphiql). By default, for security, only connections from `localhost` are permitted. To listen on all interfaces, add the `-insecure-rest-server` flag to the daemon startup command.
To use the GraphQL API, connect your GraphQL client to `http://localhost:3085/graphql` or open in your browser to use the [GraphiQL IDE](https://github.com/graphql/graphiql).

In addition to information about the running node, the GraphQL API can return data about the network's latest blocks. However, as the blockchain's historical state is not persisted in Mina, only blocks in the node's transition frontier are returned, i.e., the last `k` blocks. For other historical data, use the archive node that is designed to retain and retrieve historical data.
- By default, an HTTP server runs on port `3085`. You can configure a different port, use the `-rest-port` flag with the daemon startup command.

The full Mina GraphQL schema is available [here](https://github.com/MinaProtocol/mina/blob/develop/graphql_schema.json).
- The default security permits only connections from `localhost`. To listen on all interfaces, add the `-insecure-rest-server` flag to the daemon startup command.

In addition to information about the running node, the GraphQL API can return data about the network's latest blocks. However, as the blockchain's historical state is not persisted in Mina, only blocks in the node's transition frontier are returned, i.e., the last `k` blocks. For other historical data, use the [Archive Node](/node-operators/archive-node) that is designed to retain and retrieve historical data.

The full Mina GraphQL schema is available [https://github.com/MinaProtocol/mina/blob/develop/graphql_schema.json](https://github.com/MinaProtocol/mina/blob/develop/graphql_schema.json).
barriebyron marked this conversation as resolved.
Show resolved Hide resolved

### Queries

The Mina GraphQL API has a number of [queries](https://docs.minaprotocol.com/node-operators/querying-data) to extract data from a running node. [GraphQL queries](https://graphql.org/learn/queries/) allow specifying the data to be returned in the response. For example to get the latest block and creator information known to the daemon:
The Mina GraphQL API has a number of [queries](/node-operators/querying-data) to extract data from a running node. [GraphQL queries](https://graphql.org/learn/queries/) allow specifying the data to be returned in the response. For example, to get the latest block and creator information known to the daemon:
barriebyron marked this conversation as resolved.
Show resolved Hide resolved

```
query {
Expand All @@ -49,7 +53,7 @@ query {
}
```

The following query requests all pending transactions in the [transaction pool](#) together with their fees. This query may be used to generate an estimate of a suggested fee for a transaction:
The following query requests all pending transactions in the transaction pool together with their fees. This query can be used to generate an estimate of a suggested fee for a transaction:

```
query {
Expand Down Expand Up @@ -88,15 +92,11 @@ curl -d '{"query": "{
}"}' -H 'Content-Type: application/json' http://localhost:3085/graphql
```

### Mutations:
### Mutations

GraphQL mutations modify the running node in some way. For example, mutations may be used to send a payment, create a new account, or to add additional peers.

:::tip

Consult the [GraphQL schema](https://docs.minaprotocol.com/graphql-docs/mutation.doc.html) for all available mutations.

:::
Consult the GraphQL schema for all available mutations.

Adding a new peer:

Expand All @@ -110,17 +110,17 @@ mutation {
}
```

Update a snark worker to use a fee of 0.1 mina:
Update a SNARK worker to use a fee of 0.1 MINA:

```
mutation {
setSnarkWorkFee(input: {fee: "100000000"})
}
```

### Subscriptions:
### Subscriptions

A GraphQL [subscription](https://docs.minaprotocol.com/graphql-docs/subscription.doc.html) allows a GraphQL client to have data pushed to it when an event occurs. In Mina, there are subscriptions for:
A GraphQL subscription allows a GraphQL client to have data pushed to it when an event occurs. In Mina, there are subscriptions for:

- _newSyncUpdate_ - occurs when the sync status of the node changes.
- _newBlock_ - occurs when a new block is received.
Expand All @@ -143,14 +143,14 @@ subscription {
}
```

The new block subscription may also be limited to only return new blocks created by a defined public key with the `publicKey` argument.
The new block subscription can also be limited to return only new blocks created by a defined public key with the `publicKey` argument.

### GraphQL Public Proxy

While exposing the GraphQL API to the internet is not recommended, an implementation of a [GraphQL proxy](https://github.com/MinaProtocol/mina/tree/master/automation/services/graphql-public-proxy) is available that removes the queries that pose a threat but still allows querying of the node's data from a public endpoint.
While exposing the GraphQL API to the internet is not recommended, an implementation of a [GraphQL proxy](https://github.com/MinaProtocol/mina/tree/master/automation/services/graphql-public-proxy) is available that removes the queries that pose a threat, but still allows querying of the node's data from a public endpoint.

### Resources

- [5-minute introduction video on Mina GraphQL API](http://bit.ly/GraphQLAPIin5)
- [5-minute introduction video on Mina GraphQL API](http://bit.ly/GraphQLAPIin5) Coda
barriebyron marked this conversation as resolved.
Show resolved Hide resolved
- [First steps with the Mina GraphQL API](https://garethtdavies.com/crypto/first-steps-with-coda-graphql-api.html)
- [Introduction to GraphQL](https://graphql.org/learn/)
Loading