diff --git a/docs/node-developers/graphql-api.mdx b/docs/node-developers/graphql-api.mdx index 7282141d0..5c74aa637 100644 --- a/docs/node-developers/graphql-api.mdx +++ b/docs/node-developers/graphql-api.mdx @@ -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). ### 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: ``` query { @@ -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 { @@ -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: @@ -110,7 +110,7 @@ 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 { @@ -118,9 +118,9 @@ mutation { } ``` -### 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. @@ -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 - [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/)