Skip to content

index.md

Latest commit

 

History

History
194 lines (149 loc) · 6.67 KB

index.md

File metadata and controls

194 lines (149 loc) · 6.67 KB
Raw

API Overview

This page groups the HTTP surface by feature instead of trying to duplicate the OpenAPI output.

Most user-facing JSON / REST endpoints live under:

/api/v1

Primary vs. Follower

The repository exposes two HTTP node modes:

  • primary
    • ordinary user REST API
    • public sharing API
    • remote-node reverse-tunnel internal entry /api/v1/internal/remote-tunnel/*
    • WebDAV
    • frontend pages
    • health checks
  • follower
    • health checks
    • internal object storage protocol /api/v1/internal/storage/*

So anything used by a browser, a frontend SDK, or a public share page is usually in this directory. The two internal paths above are between primary and follower nodes only.

Endpoints outside /api/v1

The following capabilities are intentionally mounted elsewhere:

  • health checks: /health*
  • direct download links: /d/{token}/{filename}
  • preview links: /pv/{token}/{filename}
  • WebDAV: default /webdav
  • frontend pages, public share pages, and static fallback routes: registered last on the primary node

Unified response shape

Most JSON APIs use the same wrapper:

{
  "code": "success",
  "msg": "",
  "data": {}
}

Field meaning:

  • code: stable string ApiErrorCode; success means success
  • msg: human-readable fallback message
  • data: payload, omitted by some successful endpoints

Error responses also include an error object:

{
  "code": "auth.credentials_failed",
  "msg": "Invalid Credentials",
  "error": {
    "retryable": false,
    "diagnostic": {
      "kind": "auth",
      "message": "Invalid Credentials"
    }
  }
}

The public error contract has one stable code source: the top-level code. The nested error object carries behavior hints such as retryable and optional redacted diagnostics under diagnostic.kind / diagnostic.message.

Storage connection tests, storage actions, and remote-node probes return administrator-facing failure context through error.diagnostic. Successful connection tests still return an empty success payload; probe details are no longer returned as a success response body.

Error-code rules

  • Backend responses must write top-level code: ApiErrorCode.
  • ApiErrorInfo may expose only retryable and redacted diagnostic; do not reintroduce code, subcode, internal_code, or api_code under error.
  • New user-visible errors should add or reuse a stable ApiErrorCode instead of relying on message text.
  • Client copy and branching should use code, while msg remains a human-readable fallback.

Non-JSON endpoints

The following responses are raw content instead of ApiResponse:

  • file downloads
  • direct download links
  • preview links
  • share stream sessions
  • thumbnails
  • image previews
  • archive-download ZIP streams
  • share file downloads
  • share thumbnails
  • share image previews
  • uploaded avatars
  • storage event streams
  • WOPI CheckFileInfo and content callbacks
  • WebDAV responses
  • Prometheus metrics
  • follower object streams /api/v1/internal/storage/objects/{tail:.*}
  • primary reverse-tunnel WebSocket /api/v1/internal/remote-tunnel/connect

Public frontend bootstrap config, branding, preview-app configuration, thumbnail support, media-data support, and remote enrollment are unauthenticated, but they are still ordinary /api/v1/public/* JSON endpoints.

Supported authentication modes

REST / frontend

  • HttpOnly cookie
  • Authorization: Bearer <jwt>

WebDAV

  • Authorization: Basic ...

Follower internal storage protocol

  • primary-signed headers:
    • x-aster-access-key
    • x-aster-timestamp
    • x-aster-nonce
    • x-aster-signature
  • some object GET / PUT operations also accept presigned query parameters

Remote-tunnel internal entry

  • the follower connects to the primary's /api/v1/internal/remote-tunnel/* with remote-node signatures
  • this entry is for reverse-tunnel polling, completion callbacks, and WebSocket streaming only

Workspace scopes

There are two protected workspace types:

  • personal space: /files, /folders, /batch, /search, /shares, /tags, /trash
  • team space: the same semantics, but prefixed with /teams/{team_id}

Typical team paths:

/api/v1/teams/{team_id}/folders
/api/v1/teams/{team_id}/files/{id}
/api/v1/teams/{team_id}/batch/move
/api/v1/teams/{team_id}/search
/api/v1/teams/{team_id}/shares
/api/v1/teams/{team_id}/tags
/api/v1/teams/{team_id}/trash
/api/v1/teams/{team_id}/tasks
/api/v1/teams/{team_id}/tasks/offline-download
/api/v1/teams/{team_id}/webdav-accounts

In other words, team spaces reuse the same file / folder / search / tag / trash / task / WebDAV-account semantics under a team scope instead of using a separate business model.

Module index

Useful clusters to read first:

  • upload and versioning: Files
  • MFA, passkeys, external auth, and login sessions: Authentication
  • archive-only preview: Files, Sharing, and Background tasks
  • batch delete / move / copy / package download: Batch operations
  • trash restore and purge: Trash
  • tags, entity bindings, and tag-filtered search: Tags and Search
  • search, file categories, extension filters, and tag filters: Search
  • task retry and storage migration tasks: Background tasks
  • team management and team workspaces: Teams
  • public shares, preview links, and stream sessions: Sharing
  • Office / WOPI preview and callbacks: WOPI
  • WebDAV, accounts, and DeltaV: WebDAV
  • login page, anonymous page, thumbnail / media-data support, and remote enrollment: Public API
  • internal object protocol and reverse-tunnel control plane: Internal storage protocol
  • admin policies, remote nodes, storage migration, file / blob observability, external auth providers, locks, runtime config, and audit: Admin API

OpenAPI registration lives in src/api/openapi.rs, but the actual runtime route registration still comes from src/api/primary.rs, src/api/follower.rs, and src/api/routes/**. If the OpenAPI spec and the route code disagree, trust the route code first and then repair the spec.