From 62cbacbd534cb57fbceda38ea5ce2ee12bedce92 Mon Sep 17 00:00:00 2001 From: ronny-mysten <118224482+ronny-mysten@users.noreply.github.com> Date: Mon, 12 Feb 2024 14:19:15 -0700 Subject: [PATCH] [docs][easy] Some graphql beta cleanup (#16136) ## Description Describe the changes or additions included in this PR. ## Test Plan How did you test the new or updated feature? --- If your changes are not user-facing and do not break anything, you can skip the following section. Otherwise, please briefly describe what has changed under the Release Notes section. ### Type of Change (Check all that apply) - [ ] protocol change - [ ] user-visible impact - [ ] breaking change for a client SDKs - [ ] breaking change for FNs (FN binary must upgrade) - [ ] breaking change for validators or node operators (must upgrade binaries) - [ ] breaking change for on-chain data layout - [ ] necessitate either a data wipe or data migration ### Release notes --- docs/content/references/sui-api.mdx | 2 +- .../references/sui-api/beta-graph-ql.mdx | 143 ------------------ 2 files changed, 1 insertion(+), 144 deletions(-) delete mode 100644 docs/content/references/sui-api/beta-graph-ql.mdx diff --git a/docs/content/references/sui-api.mdx b/docs/content/references/sui-api.mdx index a2b68ebe4ac70..df5a2bacf61b4 100644 --- a/docs/content/references/sui-api.mdx +++ b/docs/content/references/sui-api.mdx @@ -4,7 +4,7 @@ title: Sui API :::info -The Sui API is upgrading to use GraphQL soon. See [GraphQL RPC Beta](./sui-api/beta-graph-ql.mdx) for details. +The Sui API is upgrading to GraphQL. See [Sui GraphQL RPC](../concepts/graphql-rpc.mdx) for more information. ::: diff --git a/docs/content/references/sui-api/beta-graph-ql.mdx b/docs/content/references/sui-api/beta-graph-ql.mdx deleted file mode 100644 index 9c5842a2d3ff3..0000000000000 --- a/docs/content/references/sui-api/beta-graph-ql.mdx +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: GraphQL RPC Beta -description: The Sui API is migrating from JSON RPC to a GraphQL RPC soon. A beta version is available to you for testing. ---- - -:::info - -This is a beta version providing a READ ONLY snapshot of the Sui Mainnet and Testnet networks. That is, these snapshots provide data up to a fixed checkpoint and are frozen. The beta version is made available for you to get familiar with the upcoming RPC 2.0 in an interactive manner. - -::: - -GraphQL is an open-source data query and manipulation language designed to facilitate building expressive APIs and services that require complex data querying. - -We are providing an early beta version (feature development continues) of the envisioned RPC 2.0, for `mainnet` and `testnet`, where users have access to a READ-ONLY snapshot of the two networks. This is not intended for production-ready applications, but more as a playground to get familiar with the upcoming GraphQL RPC. The [Appendix](#appendix) provides a description on the GraphQL schema. For examples, see the [Query Examples](#query-examples) section. - -## Using Sui GraphQL RPC - -Currently, there is one available playground for Sui GraphQL Service: -- `mainnet`: https://graphql-beta.mainnet.sui.io/ - -This instance runs the GraphQL IDE, an interactive IDE with autocomplete support and in-built documentation. - -The endpoint can also be queried using `curl` by passing the query to the call: -```shell -# basic query -curl -X POST https://graphql-beta.mainnet.sui.io \ - --header "Content-Type: application/json" \ - --data '{ - "query": "query { epoch { referenceGasPrice } }" - }' -# query with variables -curl -X POST https://graphql-beta.mainnet.sui.io \ - --header "Content-Type: application/json" \ - --data '{ - "query": "query ($epochID: Int!) { epoch(id: $epochID) { referenceGasPrice } }", "variables": { "epochID": 123 } - }' -``` - - -## Query examples - -An extensive list of query examples is available in the Sui repository: https://github.com/MystenLabs/sui/tree/ef4c2e592b1e3ebb03803d19fd405ff0b65f7f59/crates/sui-graphql-rpc/examples. -This doc collects all the examples into one file: https://github.com/MystenLabs/sui/blob/ef4c2e592b1e3ebb03803d19fd405ff0b65f7f59/crates/sui-graphql-rpc/docs/examples.md. - -Any existing addresses/object IDs in these examples refer to data served by the `graphql-beta.mainnet.sui.io` service only. - -## Limits - -To accommodate the rich and flexible nature of GraphQL queries, the service applies various constraints to make sure each request does not use too many resources. The following limits are in place for the beta: - -- **Rate limiting** prevents too many requests in quick succession from the same address. -- There are limits on the **number of nodes (field names)** a query can have, and the **depth (nesting level of the query)** as queries with more nodes, or deeply nested nodes can lead to more database queries. -- Before the service sends a database query, it **estimates the cost of that DB query**, and imposes a limit on this, to catch small GraphQL queries that have an outsized impact on the database. -- There is an overall **timeout** on how long a query can take. - -### Limits Introspection - -The `serviceConfig` query field can be queried to return the exact limits imposed by the service: - -```graphql -query { - serviceConfig { - maxQueryDepth - maxQueryNodes - maxDbQueryCost - maxQueryVariables - maxQueryFragments - requestTimeoutMs - } -} -``` - -Passing the `X-Sui-RPC-Show-Usage` header will prompt the service to add a `usage` extension to the response which includes details on how many of each resource the query did use. At the time of writing, this is supported for the query's depth, node count, variable count and fragment count. - -### Future Limits - -As with other parts of the system we expect the limits we employ to evolve as we productionise the service: - -- A limit will be added on the total number of output nodes, to limit the negative consequences of small queries that are cheap to run but produce a lot of data. -- Support for estimating the cost to the database will be extended from per-query to cumulative, to account for GraphQL's ability to send multiple queries in one. - -There are also a number of areas of active exploration: - -- Extending the node count and depth limits to a more sophisticated calculation that limits the number of database roundtrips on the critical path. -- Revisiting the limits on query variables and fragments to be more generous or non-existent. - -## Unsupported Features and Known Issues - -As this is only a beta version, there are a few unsupported features and/or limitations: -- There are no performance optimizations, thus some queries may be slower than expected -- Executing transactions and other information on-chain is not possible - the beta release is a READ-ONLY service -- Queries requesting stake related information might be a bit slower or fail the first time, depending on an internal cache. If it fails, try again after a couple of minutes. - -The following parts of the draft schema are are not available at the time of writing (2023-10-31), either because they are under development or out of scope for this beta. For a list of supported features, please consult the documentation in the [online IDE](https://graphql-beta.mainnet.sui.io/): - -### Top-level -- `Query.availableRange` -- `Query.coinMetadata` - -### TransactionBlock -- `kind` is missing structured data for certain kinds of transaction - -### TransactionBlockEffects -- `objectReads` - -### ObjectOwner -Object Owner refers to any type (`Address`, `Owner`, `Object`) that could own other objects. The following fields are not supported on these types: - -- `nameServiceConnection` -- `dynamicField` -- `dynamicFieldConnection` - -### Validator -- `apy` - -### Filters -All filters do not support combination (`any`, `all`, `not`) filters, and the following specific filters are to be implemented: - -- `ObjectFilter`: Filtering by package, module and type, and filtering by object key (ID and version). -- `EventFilter`: Filtering by event package, module or type. -- `TransactionBlockFilter`: Filtering by the address that paid for the transaction, the start or end time. - -### Executing Transactions -Execution is unsupported and out of scope for this beta. - -- `Query.dryRunTransactionBlock` -- `Mutation.executeTransactionBlock` - -### Subscriptions -Subscription APIs are unsupported and out of scope for this beta. - -- `Subscription.events` -- `Subscription.transactions` - -# Feedback - -We are happy to hear your feedback. Please share your thoughts in a reply to [the announcement post](https://forums.sui.io/t/launching-the-beta-graphql-rpc-service/45104), or in our usual social channels. - -## Appendix - -Call this endpoint to get the schema that the server is currently using: - -- `mainnet` - https://graphql-beta.mainnet.sui.io/schema