Api Interface - TAPLE Core

Overview

The Api struct provides methods to perform all available read and write operations on a TAPLE node. It serves as the primary interface for interacting with the node’s functionality.

Api Struct

pub struct Api {
    peer_id: PeerId,
    controller_id: String,
    public_key: Vec<u8>,
    sender: SenderEnd<APICommands, ApiResponses>,
}

Fields

peer_id

PeerId

The libp2p peer identifier of the node.

controller_id

String

The controller identifier string.

public_key

Vec<u8>

The public key bytes of the node.

Constructor

new

Creates a new Api instance.

pub fn new(
    peer_id: PeerId,
    controller_id: String,
    public_key: Vec<u8>,
    sender: SenderEnd<APICommands, ApiResponses>,
) -> Self

This constructor is typically called internally by Node::build and you won’t need to call it directly.

Accessor Methods

peer_id

Returns the peer ID of the node.

pub fn peer_id(&self) -> &PeerId

controller_id

Returns the controller ID of the node.

pub fn controller_id(&self) -> &String

public_key

Returns the public key of the node.

pub fn public_key(&self) -> &Vec<u8>

Subject Methods

get_subjects

Allows to get all subjects known to the current node, regardless of their governance.

pub async fn get_subjects(
    &self,
    namespace: String,
    from: Option<String>,
    quantity: Option<i64>,
) -> Result<Vec<SubjectData>, ApiError>

namespace

String

required

The namespace to filter subjects. Use empty string for all namespaces.

from

Option<String>

Starting point for pagination. Accepts negative values to page from the end.

quantity

Option<i64>

Number of subjects to return.

subjects

Vec<SubjectData>

List of subject data including governance subjects.

Usage Example

// Get all subjects
let subjects = api.get_subjects("".to_string(), None, None).await?;

// Get first 10 subjects
let subjects = api.get_subjects("".to_string(), None, Some(10)).await?;

// Get last 10 subjects (negative pagination)
let subjects = api.get_subjects("".to_string(), Some("-1".to_string()), Some(10)).await?;

get_subject

Allows to obtain a specified subject by its identifier.

pub async fn get_subject(
    &self, 
    subject_id: DigestIdentifier
) -> Result<SubjectData, ApiError>

subject_id

DigestIdentifier

required

The identifier of the subject to retrieve.

subject

SubjectData

The subject data.

Possible Errors

ApiError::InvalidParameters - If the specified identifier does not match a valid DigestIdentifier
ApiError::NotFound - If the subject does not exist

Usage Example

use taple_core::identifier::DigestIdentifier;

let subject_id = DigestIdentifier::from_str("Jx8T...")?;
let subject = api.get_subject(subject_id).await?;
println!("Subject state: {:?}", subject);

get_subjects_by_governance

Gets subjects filtered by governance ID.

pub async fn get_subjects_by_governance(
    &self,
    governance_id: DigestIdentifier,
    from: Option<String>,
    quantity: Option<i64>,
) -> Result<Vec<SubjectData>, ApiError>

governance_id

DigestIdentifier

required

The governance identifier to filter by.

from

Option<String>

Starting point for pagination.

quantity

Option<i64>

Number of subjects to return.

get_governances

Allows to obtain all subjects that model existing governance in the node.

pub async fn get_governances(
    &self,
    namespace: String,
    from: Option<String>,
    quantity: Option<i64>,
) -> Result<Vec<SubjectData>, ApiError>

namespace

String

required

The namespace to filter governances.

from

Option<String>

Starting point for pagination.

quantity

Option<i64>

Number of governances to return.

get_governance_subjects

Gets subjects associated with a specific governance.

pub async fn get_governance_subjects(
    &self,
    governance_id: DigestIdentifier,
    from: Option<String>,
    quantity: Option<i64>,
) -> Result<Vec<SubjectData>, ApiError>

Event Methods

get_events

Allows to obtain events from a specific subject.

pub async fn get_events(
    &self,
    subject_id: DigestIdentifier,
    from: Option<i64>,
    quantity: Option<i64>,
) -> Result<Vec<Signed<Event>>, ApiError>

subject_id

DigestIdentifier

required

The identifier of the subject.

from

Option<i64>

Starting sequence number. Negative values page from the end.

quantity

Option<i64>

Number of events to return.

events

Vec<Signed<Event>>

List of signed events.

Usage Example

// Get all events for a subject
let events = api.get_events(subject_id, None, None).await?;

// Get first 10 events
let events = api.get_events(subject_id, Some(0), Some(10)).await?;

// Get last 5 events
let events = api.get_events(subject_id, Some(-1), Some(5)).await?;

get_event

Gets a specific event by subject ID and sequence number.

pub async fn get_event(
    &self,
    subject_id: DigestIdentifier,
    sn: u64,
) -> Result<Signed<Event>, ApiError>

subject_id

DigestIdentifier

required

The subject identifier.

u64

required

The sequence number of the event.

Request Methods

external_request

Allows to make a request to the node from an external invoker.

pub async fn external_request(
    &self,
    event_request: Signed<EventRequest>,
) -> Result<DigestIdentifier, ApiError>

event_request

Signed<EventRequest>

required

A signed event request.

request_id

DigestIdentifier

The identifier of the created request.

Usage Example

use taple_core::EventRequest;

let event_request = EventRequest::Create { /* ... */ };
let signed_request = sign_request(event_request)?;
let request_id = api.external_request(signed_request).await?;
println!("Request created: {}", request_id);

get_request

Retrieves a request by its identifier.

pub async fn get_request(
    &self,
    request_id: DigestIdentifier,
) -> Result<TapleRequest, ApiError>

request_id

DigestIdentifier

required

The request identifier.

Approval Methods

The following methods are only available when the approval feature is enabled.

get_pending_requests

Allows to obtain all voting requests pending to be resolved in the node.

#[cfg(feature = "approval")]
pub async fn get_pending_requests(&self) -> Result<Vec<ApprovalEntity>, ApiError>

requests

Vec<ApprovalEntity>

List of pending approval requests.

These requests are received from other nodes in the network when they try to update a governance subject.

get_single_request

Allows to obtain a single voting request.

#[cfg(feature = "approval")]
pub async fn get_single_request(
    &self,
    id: DigestIdentifier,
) -> Result<ApprovalEntity, ApiError>

DigestIdentifier

required

The request identifier.

Possible Errors

ApiError::InternalError - If an internal error occurs
ApiError::NotFound - If the requested request does not exist

approval_request

Allows to vote on a voting request that exists in the system.

#[cfg(feature = "approval")]
pub async fn approval_request(
    &self,
    request_id: DigestIdentifier,
    acceptance: bool,
) -> Result<ApprovalEntity, ApiError>

request_id

DigestIdentifier

required

The identifier of the request to vote on.

acceptance

bool

required

true to accept the request, false to reject it.

approval

ApprovalEntity

The updated approval entity after voting.

Possible Errors

ApiError::InternalError - If an internal error occurs during operation execution
ApiError::NotFound - If the request does not exist in the system
ApiError::InvalidParameters - If the specified request identifier does not match a valid DigestIdentifier
ApiError::VoteNotNeeded - If the node’s vote is no longer required

Usage Example

// Accept a pending request
let approval = api.approval_request(request_id, true).await?;

// Reject a pending request
let approval = api.approval_request(request_id, false).await?;

get_approval

Gets a specific approval by request ID.

#[cfg(feature = "approval")]
pub async fn get_approval(
    &self,
    request_id: DigestIdentifier,
) -> Result<ApprovalEntity, ApiError>

get_approvals

Gets approvals with optional filtering by state.

#[cfg(feature = "approval")]
pub async fn get_approvals(
    &self,
    state: Option<ApprovalState>,
    from: Option<String>,
    quantity: Option<i64>,
) -> Result<Vec<ApprovalEntity>, ApiError>

state

Option<ApprovalState>

Filter approvals by state (Pending, Approved, Rejected, etc.).

from

Option<String>

Starting point for pagination.

quantity

Option<i64>

Number of approvals to return.

Authorization Methods

add_preauthorize_subject

Adds a subject to the preauthorized list with specified providers.

pub async fn add_preauthorize_subject(
    &self,
    subject_id: &DigestIdentifier,
    providers: &HashSet<KeyIdentifier>,
) -> Result<(), ApiError>

subject_id

&DigestIdentifier

required

The subject identifier to preauthorize.

providers

&HashSet<KeyIdentifier>

required

Set of provider key identifiers.

get_all_allowed_subjects_and_providers

Gets all preauthorized subjects and their providers.

pub async fn get_all_allowed_subjects_and_providers(
    &self,
    from: Option<String>,
    quantity: Option<i64>,
) -> Result<Vec<(DigestIdentifier, HashSet<KeyIdentifier>)>, ApiError>

from

Option<String>

Starting point for pagination.

quantity

Option<i64>

Number of items to return.

Cryptographic Methods

add_keys

Adds cryptographic keys with the specified derivator.

pub async fn add_keys(
    &self, 
    derivator: KeyDerivator
) -> Result<KeyIdentifier, ApiError>

derivator

KeyDerivator

required

The key derivation algorithm to use (Ed25519, Secp256k1).

key_identifier

KeyIdentifier

The identifier of the newly created key.

get_validation_proof

Gets the validation proof for a subject.

pub async fn get_validation_proof(
    &self,
    subject_id: DigestIdentifier,
) -> Result<(HashSet<Signature>, ValidationProof), ApiError>

subject_id

DigestIdentifier

required

The subject identifier.

signatures

HashSet<Signature>

Set of signatures for the validation.

proof

ValidationProof

The validation proof data.

Source Reference

For more details, see the source code at core/src/api/api.rs:32-447.

Core API

Requests

Cryptography

Data Models

Database

Notifications

​Overview

​Api Struct

​Fields

​Constructor

​new

​Accessor Methods

​peer_id

​controller_id

​public_key

​Subject Methods

​get_subjects

​Usage Example

​get_subject

​Possible Errors

​Usage Example

​get_subjects_by_governance

​get_governances

​get_governance_subjects

​Event Methods

​get_events

​Usage Example

​get_event

​Request Methods

​external_request

​Usage Example

​get_request

​Approval Methods

​get_pending_requests

​get_single_request

​Possible Errors

​approval_request

​Possible Errors

​Usage Example

​get_approval

​get_approvals

​Authorization Methods

​add_preauthorize_subject

​get_all_allowed_subjects_and_providers

​Cryptographic Methods

​add_keys

​get_validation_proof

​Source Reference

Build docs developers (and LLMs) love

Overview

Api Struct

Fields

Constructor

new

Accessor Methods

peer_id

controller_id

public_key

Subject Methods

get_subjects

Usage Example

get_subject

Possible Errors

Usage Example

get_subjects_by_governance

get_governances

get_governance_subjects

Event Methods

get_events

Usage Example

get_event

Request Methods

external_request

Usage Example

get_request

Approval Methods

get_pending_requests

get_single_request

Possible Errors

approval_request

Possible Errors

Usage Example

get_approval

get_approvals

Authorization Methods

add_preauthorize_subject

get_all_allowed_subjects_and_providers

Cryptographic Methods

add_keys

get_validation_proof

Source Reference