|
| 1 | +--- |
| 2 | +title: "Aptos Fullnode REST API" |
| 3 | +--- |
| 4 | + |
| 5 | +import { LinkCard, Aside, CardGrid, Card } from '@astrojs/starlight/components'; |
| 6 | + |
| 7 | + |
| 8 | + |
| 9 | +{/* import { Card, Cards } from '@components/index' */} |
| 10 | + |
| 11 | +# Aptos Fullnode REST API |
| 12 | + |
| 13 | +This API - embedded into Fullnodes - provides a simple, low latency, yet low-level way of reading state and submitting transactions to the Aptos Blockchain. It also supports transaction simulation. |
| 14 | +For more advanced queries, we recommend using the [Indexer GraphQL API](../indexer.mdx). |
| 15 | + |
| 16 | +## Fullnode REST API Explorer |
| 17 | + |
| 18 | +<CardGrid> |
| 19 | + <LinkCard href="https://fullnode.mainnet.aptoslabs.com/v1/spec#/" title="Mainnet Fullnode REST API" description={"REST API Explorer for Mainnet"} /> |
| 20 | + <LinkCard href="https://fullnode.testnet.aptoslabs.com/v1/spec#/" title="Testnet Fullnode REST API" description={"REST API Explorer for Testnet"} /> |
| 21 | + <LinkCard href="https://fullnode.devnet.aptoslabs.com/v1/spec#/" title="Devnet Fullnode REST API" description={"REST API Explorer for Devnet"} /> |
| 22 | +</CardGrid> |
| 23 | + |
| 24 | +## Understanding rate limits |
| 25 | + |
| 26 | +As with the [Aptos Indexer](../indexer/indexer-api.mdx), the Aptos REST API has a rate limit of 5000 |
| 27 | +requests per five minutes by IP address, whether submitting transactions or querying the API on Aptos-provided nodes. |
| 28 | +(As a node operator, you may raise those limits on your own node.) Note that this limit can change with or without prior |
| 29 | +notice. |
| 30 | + |
| 31 | +## Viewing current and historical state |
| 32 | + |
| 33 | +Most integrations into the Aptos blockchain benefit from a holistic and comprehensive overview of the current and |
| 34 | +historical state of the blockchain. Aptos provides historical transactions, state, and events, all the result of |
| 35 | +transaction execution. |
| 36 | + |
| 37 | +- Historical transactions specify the execution status, output, and tie to related events. Each transaction has a unique |
| 38 | +version number associated with it that dictates its global sequential ordering in the history of the blockchain ledger. |
| 39 | +- The state is the representation of all transaction outputs up to a specific version. In other words, a state version |
| 40 | +is the accumulation of all transactions inclusive of that transaction version. |
| 41 | +- As transactions execute, they may emit events. [Events](../../network/blockchain/events.mdx) are hints about changes in on-chain |
| 42 | +data. |
| 43 | + |
| 44 | +<Aside type="note"> |
| 45 | +Ensure the [fullnode](../../network/nodes/networks.mdx) you are communicating with is up-to-date. The fullnode must reach the |
| 46 | +version containing your transaction to retrieve relevant data from it. There can be latency from the fullnodes |
| 47 | +retrieving state from [validator fullnodes](../../network/blockchain/fullnodes.mdx), which in turn rely upon |
| 48 | +[validator nodes](../../network/blockchain/validator-nodes.mdx) as the source of truth. |
| 49 | +</Aside> |
| 50 | + |
| 51 | +The storage service on a node employs two forms of pruning that erase data from nodes: |
| 52 | + |
| 53 | +- state |
| 54 | +- events, transactions, and everything else |
| 55 | + |
| 56 | +While either of these may be disabled, storing the state versions is not particularly sustainable. |
| 57 | + |
| 58 | +Events and transactions pruning can be disabled via setting the [`enable_ledger_pruner`](https://github.com/aptos-labs/aptos-core/blob/cf0bc2e4031a843cdc0c04e70b3f7cd92666afcf/config/src/config/storage_config.rs#L141) |
| 59 | +to `false` in `storage_config.rs`. This is default behavior in Mainnet. In the near future, Aptos will provide indexers |
| 60 | + that mitigate the need to directly query from a node. |
| 61 | + |
| 62 | +The REST API offers querying transactions and events in these ways: |
| 63 | + |
| 64 | +- [Transactions for an account](https://api.devnet.aptoslabs.com/v1/spec#/operations/get_account_transactions) |
| 65 | +- [Transactions by version](https://api.devnet.aptoslabs.com/v1/spec#/operations/get_transaction_by_version) |
| 66 | +- [Events by event handle](https://api.devnet.aptoslabs.com/v1/spec#/operations/get_events_by_event_handle) |
| 67 | + |
| 68 | +## Reading state with the View function |
| 69 | + |
| 70 | +View functions do not modify blockchain state when called from the API. A [View function](https://github.com/aptos-labs/aptos-core/blob/main/api/src/view_function.rs) |
| 71 | + and its [input](https://github.com/aptos-labs/aptos-core/blob/main/api/types/src/view.rs) can be used to read |
| 72 | + potentially complex on-chain state using Move. For example, you can evaluate who has the highest bid in an auction |
| 73 | + contract. Here are related files: |
| 74 | + |
| 75 | +- [`view_function.rs`](https://github.com/aptos-labs/aptos-core/blob/main/api/src/tests/view_function.rs) for an example |
| 76 | +- related [Move](https://github.com/aptos-labs/aptos-core/blob/90c33dc7a18662839cd50f3b70baece0e2dbfc71/aptos-move/framework/aptos-framework/sources/coin.move#L226) code |
| 77 | +- [specification](https://github.com/aptos-labs/aptos-core/blob/90c33dc7a18662839cd50f3b70baece0e2dbfc71/api/doc/spec.yaml#L8513). |
| 78 | + |
| 79 | +The view function operates like the Aptos simulation API, |
| 80 | +though with no side effects and an accessible output path. View functions can be called via the `/view` endpoint. Calls |
| 81 | +to view functions require the module and function names along with input type parameters and values. |
| 82 | + |
| 83 | +A function does not have to be immutable to be tagged as `#[view]`, but if the function is mutable it will not result in |
| 84 | +state mutation when called from the API. If you want to tag a mutable function as `#[view]`, consider making it private |
| 85 | +so that it cannot be maliciously called during runtime. |
| 86 | + |
| 87 | +In order to use the View functions, you need to [publish the module](../cli/working-with-move-contracts.mdx) |
| 88 | +through the [Aptos CLI](../cli.mdx). |
| 89 | + |
| 90 | +In the Aptos CLI, a view function request would look like this: |
| 91 | + |
| 92 | +```bash filename="Terminal" |
| 93 | +aptos move view --function-id devnet::message::get_message --profile devnet --args address:devnet |
| 94 | +{ |
| 95 | + "Result": [ |
| 96 | + "View functions rock!" |
| 97 | + ] |
| 98 | +} |
| 99 | +``` |
| 100 | + |
| 101 | +In the TypeScript SDK, a view function request would look like this: |
| 102 | + |
| 103 | +```ts filename="index.ts" |
| 104 | +import { Aptos } from "@aptos-labs/ts-sdk"; |
| 105 | + |
| 106 | +const aptos = new Aptos(); |
| 107 | +const [balance] = aptos.view<[string]>({ |
| 108 | + function: "0x1::coin::balance", |
| 109 | + typeArguments: ["0x1::aptos_coin::AptosCoin"], |
| 110 | + functionArguments: [alice.accountAddress] |
| 111 | +}); |
| 112 | + |
| 113 | +expect(balance).toBe("100000000"); |
| 114 | +``` |
| 115 | + |
| 116 | +The view function returns a list of values as a vector. By default, the results are returned in JSON format; however, |
| 117 | +they can be optionally returned in Binary Canonical Serialization (BCS) encoded format. |
0 commit comments