This module provides REST API for client applications to query the Aptos blockchain.
For an Aptos node, you can view the documentation at
API routes and handlers are managed by
warp framework; endpoints/handlers are grouped into files named by resource names (e.g. accounts, transactions).
Each handler defines:
warphandler: an async function returns
Result<impl Reply, Rejection>.
index.rs is the root of all routes, it handles
GET /API and connects all resources' routes with error handling.
The service is launched with a
Context instance, which holds all external components (e.g. AptosDB, mempool sender).
Context object also serves as a facade of external components, and sharing some general functionalities across
There are four types HTTP input:
We process parameters in three stages:
warphandler (the async function passed into
warp::Filter#and_thenfunction) or endpoint handler's constructor (
For path parameter:
TargetTypeParamin the param.rs, and use it in the
warproute definition for capturing the HTTP path parameter. We don't parse the parameter at this stage, because
warpwill drop error and return
not_founderror without a meaningful message.
TargetTypeis required to implement
Param#parseuses it for parsing the HTTP path parameter string and returning
400error code with a meaningful invalid parameter error message.
Query parameters should not be required, always provide default values for the case they are not provided.
To create easy to use API, the following principles are valued
00000000000000000000000000000001; API accepts all of them as input, but all API should output consistent same format (
0x1). The API should also only expose must-have and the most stable concepts as data structure.
u64instead of integer.
Models or types are defined in the
aptos-api-types package (in the directory
These types handle the JSON serialization and deserialization between internal data types and API response JSON types.
TryFrom traits are implemented for converting between API data type and Aptos core data types instead of special constructors.
Move data are converted by procedures defined in the
convert.rs, because Move data type definitions are defined by the Move module stored in the Aptos DB. We first retrieve Move data types from the database, then convert them into API data types.
When we convert internal Move struct values into JSON, the data type information will be lost, thus we can't direct convert move struct value JSON data back to any internal data structure while deserializing HTTP request data. For this reason:
aptos_api_types::MoveValueis only used internally for converting move values into JSON before we create external facing API types (e.g.
move_core_types::value::MoveValuewhen we need.
Errors are handled by the
warp.Rejection handler defined in the
index.rs for all routes.
anyhow::Error is considered as server internal error (500) by default.
All internal errors should be converted into
aptos_api_types.Error is defined for converting
warp.Rejection with HTTP error code.
Handler tests should cover all aspects of features and functions.
TestContext is implemented to create components' stubs that API handlers are connected to.
These stubs are more close to real production components, instead of mocks, so that tests can ensure the API
handlers are working well with other components in the systems.
For example, we use real AptosDB implementation in tests for API layers to interact with the database.
Most of the utility functions are provided by the
Run integration/smoke tests in
cargo test --test "forge" "api::"
scripts/dev_setup.sh -ato setup tools.
make testinside the
Failpoint configuration example:
failpoints api::endpoint_index: 1%return api::endpoint_get_account: 1%return api::endpoint_get_account_resources: 1%return api::endpoint_get_account_modules: 1%return api::endpoint_get_transaction: 1%return api::endpoint_get_transactions: 1%return api::endpoint_get_account_transactions: 1%return api::endpoint_submit_json_transactions: 1%return api::endpoint_submit_bcs_transactions: 1%return api::endpoint_create_signing_message: 1%return api::endpoint_get_events_by_event_key: 1%return api::endpoint_get_events_by_event_handle: 1%return
Please refer to Operation document for details, including configuration, logging, metrics etc.