mars-server · api::rest

Package: mars-server · Workspace version: 0.1.0 · Module: api::rest

This reference follows declared modules and public syntax, including public implementation methods. Function bodies and constant values are omitted. Feature conditions are retained. Private-module re-exports and trait resolution require the compiler; not every declaration is a root import.

api::rest::create_entry

POST /v1/entries -- Create a new registry entry.

This handler runs behind capability-aware auth middleware. The middleware resolves the caller's session into a [Principal] and inserts it as a request extension. The handler then:

Rate-limits per publisher, keying [crate::middleware::RateLimiter] on principal.publisher_did.
Runs the full validation pipeline first (schema → DID → hash → signature → bond) so the caller can't probe whether an unauthorised publisher_did would have validated.
Enforces the publisher binding — entries whose publisher_did differs from the session's HMR are rejected with MARS-007 (InsufficientPermissions). No proxy publishing.

pub async fn create_entry(
    State(state): State<Arc<AppState>>,
    Extension(principal): Extension<Principal>,
    Extension(context): Extension<MutationContext>,
    Json(mut entry): Json<MarsEntry>,
) -> Result<Response, ServerError>;

Source line: 192.

api::rest::get_entry

GET /v1/entries/:did -- Get the latest version of an entry by DID.

pub async fn get_entry(
    State(state): State<Arc<AppState>>,
    Path(did): Path<String>,
) -> Result<impl IntoResponse, ServerError>;

Source line: 258.

api::rest::get_entry_version

GET /v1/entries/:did/versions/:version -- Get a specific version.

pub async fn get_entry_version(
    State(state): State<Arc<AppState>>,
    Path((did, version)): Path<(String, String)>,
) -> Result<impl IntoResponse, ServerError>;

Source line: 271.

api::rest::list_entry_versions

GET /v1/entries/:did/versions -- List a bounded version page, newest first.

pub async fn list_entry_versions(
    State(state): State<Arc<AppState>>,
    Path(did): Path<String>,
    Query(query): Query<EntryVersionsQuery>,
) -> Result<impl IntoResponse, ServerError>;

Source line: 284.

api::rest::get_entry_lineage

GET /v1/entries/:did/lineage -- Get an entry's canonical lineage summary.

pub async fn get_entry_lineage(
    State(state): State<Arc<AppState>>,
    Path(did): Path<String>,
) -> Result<impl IntoResponse, ServerError>;

Source line: 323.

api::rest::update_entry

PUT /v1/entries/:did -- Update an existing entry.

Requires Capability::UpdateEntry. The principal publisher must match entry.publisher_did — no proxy updates.

pub async fn update_entry(
    State(state): State<Arc<AppState>>,
    Extension(principal): Extension<Principal>,
    Extension(context): Extension<MutationContext>,
    Path(did): Path<String>,
    Json(mut entry): Json<MarsEntry>,
) -> Result<Response, ServerError>;

Source line: 343.

api::rest::delete_entry

DELETE /v1/entries/:did -- Revoke an entry.

Requires Capability::RevokeEntry. The principal publisher must match the existing entry's publisher_did; only the owner can revoke the entry.

pub async fn delete_entry(
    State(state): State<Arc<AppState>>,
    Extension(principal): Extension<Principal>,
    Extension(context): Extension<MutationContext>,
    Path(did): Path<String>,
) -> Result<Response, ServerError>;

Source line: 446.

api::rest::discover

POST /v1/discover -- Discover entries via structured JSON query.

pub async fn discover(
    State(state): State<Arc<AppState>>,
    Json(req): Json<DiscoverRequest>,
) -> Result<impl IntoResponse, ServerError>;

Source line: 499.

api::rest::discover_marsql

POST /v1/discover/marsql -- Discover entries via MARS-QL query string.

pub async fn discover_marsql(
    State(state): State<Arc<AppState>>,
    Json(req): Json<MarsQlRequest>,
) -> Result<impl IntoResponse, ServerError>;

Source line: 701.

api::rest::discover_federated

POST /v1/discover/federated -- Optional bounded local-plus-peer query.

pub async fn discover_federated(
    State(state): State<Arc<AppState>>,
    Extension(_principal): Extension<Principal>,
    Json(query): Json<MarsQuery>,
) -> Result<impl IntoResponse, ServerError>;

Source line: 712.

api::rest::create_transfer_offer

Create a signed, expiring transfer offer. This never changes ownership.

pub async fn create_transfer_offer(
    State(state): State<Arc<AppState>>,
    Extension(principal): Extension<Principal>,
    Extension(context): Extension<MutationContext>,
    Path(did): Path<String>,
    Json(req): Json<TransferOfferRequest>,
) -> Result<Response, ServerError>;

Source line: 735.

api::rest::get_transfer_offer

Read one transfer offer. Elapsed live offers are projected as expired.

pub async fn get_transfer_offer(
    State(state): State<Arc<AppState>>,
    Path(offer_id): Path<String>,
) -> Result<impl IntoResponse, ServerError>;

Source line: 823.

api::rest::accept_transfer_offer

Accept a transfer with a complete entry re-signed by the recipient.

pub async fn accept_transfer_offer(
    State(state): State<Arc<AppState>>,
    Extension(principal): Extension<Principal>,
    Extension(context): Extension<MutationContext>,
    Path(offer_id): Path<String>,
    Json(mut req): Json<TransferAcceptRequest>,
) -> Result<Response, ServerError>;

Source line: 867.

api::rest::decline_transfer_offer

Decline a transfer offer. The recipient identity comes only from Principal.

pub async fn decline_transfer_offer(
    State(state): State<Arc<AppState>>,
    Extension(principal): Extension<Principal>,
    Extension(context): Extension<MutationContext>,
    Path(offer_id): Path<String>,
    Json(req): Json<TransferDeclineRequest>,
) -> Result<Response, ServerError>;

Source line: 995.

api::rest::create_attestation

Store and verify a canonical OAS Verifiable Credential separately.

pub async fn create_attestation(
    State(state): State<Arc<AppState>>,
    Extension(principal): Extension<Principal>,
    Extension(context): Extension<MutationContext>,
    Json(req): Json<AttestationRequest>,
) -> Result<Response, ServerError>;

Source line: 1057.

api::rest::get_attestations

Read canonical attestations, filtering expired and revoked records by default.

pub async fn get_attestations(
    State(state): State<Arc<AppState>>,
    Path(did): Path<String>,
    Query(query): Query<AttestationQuery>,
) -> Result<impl IntoResponse, ServerError>;

Source line: 1169.

api::rest::create_report

POST /v1/report -- File a malicious-behaviour report against an entry.

pub async fn create_report(
    State(state): State<Arc<AppState>>,
    Extension(principal): Extension<Principal>,
    Extension(context): Extension<MutationContext>,
    Json(req): Json<ReportRequest>,
) -> Result<Response, ServerError>;

Source line: 1194.

api::rest::get_anchors

GET /v1/anchors/:did -- Get persisted anchor intents and receipts.

pub async fn get_anchors(
    State(state): State<Arc<AppState>>,
    Path(did): Path<String>,
    Query(query): Query<AnchorListQuery>,
) -> Result<impl IntoResponse, ServerError>;

Source line: 1248.

api::rest::retry_anchor

Requeue a failed or abandoned anchor intent.

pub async fn retry_anchor(
    State(state): State<Arc<AppState>>,
    Extension(principal): Extension<Principal>,
    Extension(context): Extension<MutationContext>,
    Path(intent_id): Path<String>,
) -> Result<Response, ServerError>;

Source line: 1306.

api::rest::abandon_anchor

Permanently abandon a pending, expired-claim, or failed anchor intent.

pub async fn abandon_anchor(
    State(state): State<Arc<AppState>>,
    Extension(principal): Extension<Principal>,
    Extension(context): Extension<MutationContext>,
    Path(intent_id): Path<String>,
) -> Result<Response, ServerError>;

Source line: 1349.

api::rest::get_bond

GET /v1/bonds/:bond_id -- Get a bond by ID.

pub async fn get_bond(
    State(state): State<Arc<AppState>>,
    Path(bond_id): Path<String>,
) -> Result<impl IntoResponse, ServerError>;

Source line: 1392.

api::rest::provision_bond

Admin-scoped provisioning of registry-local bond metadata.

pub async fn provision_bond(
    State(state): State<Arc<AppState>>,
    Extension(principal): Extension<Principal>,
    Extension(context): Extension<MutationContext>,
    Json(request): Json<BondProvisionRequest>,
) -> Result<Response, ServerError>;

Source line: 1405.

api::rest::health_check

GET /v1/health -- Health check endpoint (no rate limit).

pub async fn health_check(State(state): State<Arc<AppState>>) -> impl IntoResponse;

Source line: 1465.

api::rest::health_check_deep

GET /v1/health/deep -- Operator-only, rate-limited deep health check.

Runs storage, durable anchor-outbox, adapter registration, and immutable ledger-chain checks. Returns HTTP 200 so load balancers can inspect the body.

Aggregate status semantics:

"ok" — every subsystem reported ok.
"degraded" — at least one subsystem was skipped but none failed.
"down" — at least one subsystem failed.

pub async fn health_check_deep(State(state): State<Arc<AppState>>) -> impl IntoResponse;

Source line: 1482.

api::rest::list_federation_peers

GET /v1/federation/peers -- List known federation peers.

pub async fn list_federation_peers(
    State(state): State<Arc<AppState>>,
) -> Result<impl IntoResponse, ServerError>;

Source line: 1654.

api::rest::federation_peer_status

Protected operational status for configured federation peers.

pub async fn federation_peer_status(
    State(state): State<Arc<AppState>>,
) -> Result<impl IntoResponse, ServerError>;

Source line: 1665.

api::rest::update_federation_peer

pub async fn update_federation_peer(
    State(state): State<Arc<AppState>>,
    Extension(principal): Extension<Principal>,
    Extension(context): Extension<MutationContext>,
    Json(request): Json<FederationPeerUpdateRequest>,
) -> Result<Response, ServerError>;

Source line: 1680.

api::rest::federation_sync

POST /v1/federation/sync -- Handle incoming federation sync request.

pub async fn federation_sync(
    State(state): State<Arc<AppState>>,
    Json(envelope): Json<SignedFederationEnvelope<SyncRequest>>,
) -> Result<impl IntoResponse, ServerError>;

Source line: 1760.

api::rest::federation_discover

Signed peer-side MARS-QL discovery.

pub async fn federation_discover(
    State(state): State<Arc<AppState>>,
    Json(envelope): Json<SignedFederationEnvelope<FederatedDiscoveryRequest>>,
) -> Result<impl IntoResponse, ServerError>;

Source line: 1777.

Source provenance

Source: mars-server/src/api/rest.rs · SHA-256 31bb320dc19cafc960d4e359be9f971959046d4a0a27fce443fcc7806a417aa6. Package overview.

mars-server · api::rest

On this page