Struct exonum_rust_runtime::api::ServiceApiBuilder

pub struct ServiceApiBuilder { /* fields omitted */ }

Exonum service API builder which is used to add endpoints to the node API.

Examples

The example below shows a common practice of the API implementation.

use serde_derive::{Deserialize, Serialize};
use exonum::{blockchain::Schema, crypto::Hash, merkledb::ObjectHash};
use exonum_rust_runtime::api::{self, ServiceApiBuilder, ServiceApiState};

// Declare a type which describes an API specification and implementation.
pub struct MyApi;

// Declare structures for requests and responses.

// For the web backend `MyQuery` will be deserialized from the `block_height={number}` string.
#[derive(Deserialize, Clone, Copy)]
pub struct MyQuery {
    pub block_height: u64,
}

// For the web backend `BlockInfo` will be serialized into a JSON string.
#[derive(Serialize, Clone, Copy)]
pub struct BlockInfo {
    pub hash: Hash,
}

// Create API handlers.
impl MyApi {
    /// Immutable handler which returns a hash of the block at the given height.
    pub async fn block_hash(
        state: ServiceApiState,
        query: MyQuery,
    ) -> api::Result<Option<BlockInfo>> {
        let schema = state.data().for_core();
        Ok(schema
            .block_hashes_by_height()
            .get(query.block_height)
            .map(|hash| BlockInfo { hash }))
    }

    /// Simple handler without any parameters.
    pub async fn ping(_state: ServiceApiState, _query: ()) -> api::Result<()> {
        Ok(())
    }

    /// You may also use asynchronous tasks.
    pub async fn async_operation(
        _state: ServiceApiState,
        query: MyQuery,
    ) -> api::Result<Option<Hash>> {
        Ok(long_async_task(query).await)
    }
}

fn wire_api(builder: &mut ServiceApiBuilder) -> &mut ServiceApiBuilder {
    // Add `MyApi` handlers to the corresponding builder.
    builder
        .public_scope()
        .endpoint("v1/block_hash", MyApi::block_hash)
        .endpoint("v1/async_operation", MyApi::async_operation);
    // Add a mutable endpoint to the private API.
    builder
        .private_scope()
        .endpoint("v1/ping", MyApi::ping);
    builder
}

Methods

impl ServiceApiBuilder

pub fn public_scope(&mut self) -> &mut ServiceApiScope

Returns a mutable reference to the public API scope builder.

pub fn private_scope(&mut self) -> &mut ServiceApiScope

Returns a mutable reference to the private API scope builder.

pub fn blockchain(&self) -> &Blockchain

Returns a reference to the blockchain.

Trait Implementations

impl Debug for ServiceApiBuilder

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl From<ServiceApiBuilder> for ApiBuilder

fn from(inner: ServiceApiBuilder) -> Self

Performs the conversion.