Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

OpenAPI document

Every OpenXet server describes its whole HTTP API in one OpenAPI 3.1 document: the CAS, the Hub API, Git smart HTTP, Git LFS, the file gateway and the probes. Generate a client from it, give it to an agent, or browse it in any OpenAPI viewer.

WhereWhat
GET /openapi.jsonOn any running server. No credential: it describes routes, never data.
openxet openapiPrints the same bytes, without a server.
docs/reference/openapi.jsonThe copy for this release, checked in.
 
openxet openapi > openapi.json
curl -s http://127.0.0.1:8080/openapi.json | jq '.paths | keys | length'

What it holds

  • Every route the server serves, with its methods. A route is described where it is built, so the document lists exactly what the server answers: a route can't be added without its description, and a test fails if a served route and the document disagree.

  • Parameters: path, query and request headers such as Range, each with what it holds. A path parameter that ends a route, such as {path} in /api/models/{ns}/{name}/tree/{rev}/{path}, may hold /.

  • Credentials as security schemes, never as values:

    SchemeCredential
    casTokenA static token or a CAS token, as Authorization: Bearer. The CAS routes.
    accessTokenAn OpenXet access token, as Authorization: Bearer. The Hub routes.
    accessTokenBasicThe access token as the password of HTTP Basic, as git and git-lfs send it. Git, LFS and the file gateway.
    signedUrlA URL the server signed: sig and the other query parameters it signs are the credential. CAS transfer URLs and LFS capability URLs.

    An operation that also lists the empty requirement {} answers without a credential what the operator's anonymous rules allow. The document holds no example values at all.

  • Every answer, with its body's schema, and every status a route can give with the codes it carries. Every 4xx and 5xx is the error body ErrorBody, {"schema":"openxet.error.v1","code","message","hint"}; the Hub, LFS and gateway routes answer HubErrorBody, which adds huggingface.co's error field and the X-Error-Code and X-Error-Message headers; Git routes answer GitErrorText, the message and hint as text/plain, which git prints as remote: lines. The one exception is the 416 of a file read, which carries only Content-Range, as HTTP defines it.

  • Headers every answer carries: X-Request-Id, and Cache-Control: no-store on every route whose answer depends on the caller's credential.

Conventions

  • Tags group the routes: cas, hub, openxet (the labels API), git, lfs, gateway, health and meta (this document).
  • Hub types. Each repository route is listed once per Hub type, /api/models/…, /api/datasets/…, /api/spaces/… and /api/kernels/…, and each Git and LFS route once unprefixed and once under /datasets/…, /spaces/… and /kernels/…. They behave alike through the repository's labels.
  • operationId is the method and the path's words: get_api_models_ns_name_tree_rev.
  • HEAD. A GET route also answers HEAD with the same status and headers and no body; it is not listed separately. The CAS transfer route is the exception: its HEAD is listed, and refused.
  • Shared answers. An answer several operations give is described once under components/responses, named after the first operation that gives it, and referred to from each.
  • Version. info.version is the server's version.

The CAS routes are explained in prose in CAS routes, and the LFS routes in Git LFS routes.

Keeping it current

CI runs scripts/check-openapi.sh, which fails when the checked-in copy differs from what openxet openapi prints, and the tests in crates/openxet/tests/openapi.rs, which check that the document lists every served route, is valid against the OpenAPI 3.1 JSON Schema, and is what GET /openapi.json serves. After changing a route, regenerate the copy:

cargo run -q -p openxet -- openapi > docs/reference/openapi.json

Read this page as Markdown · Report a docs issue