Library copies

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

Downloads of an edition's files the library already holds, by a branch or clerk it granted the copy to; the grant's token is the credential.

Back to the web API reference.

GET /api/copies/v1/{copy_id}/files/{index}

Streams one file of a granted copy.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: copyToken

Parameters

  • copy_idpathstringrequiredCopy id from copy.granted, on the node socket or the clerk socket.
  • indexpathinteger (int32)requiredThe file's index in the grant's files.
  • Rangeheaderstring or nullOne byte range (bytes=A-B, bytes=A- or bytes=-N); anything else reads the whole file.

Responses

  • 200The whole file. Body: BinaryBody (application/octet-stream)
  • 206The requested byte range, with Content-Range. Body: BinaryBody (application/octet-stream)
  • 401The copy token is missing, wrong or expired, or the grant no longer holds: the branch is no longer trusted or the library card is signed out, the person may no longer take the edition, or the library's files changed since the grant (unauthorized). Ask for a new grant; a clerk whose library card is signed out signs in again first. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 403The connection failed the transport policy (transport_insecure, with the check in reason). Body: TransportRefused (application/json)2 fields
    • errorstringrequiredAlways transport_insecure.
    • reasonstringrequiredThe transport check that refused the connection (plain_http, unknown_peer, untrusted_forwarding, proxy_proto_missing, proxy_proto_ambiguous, proxy_proto_not_https, public_origin_not_https, listener_mode_mismatch, node_api_misconfigured).
  • 404The index names no file of the copy (unknown_file), or the node API is not mounted on this listener (node_api_unmounted). Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 416The range starts at or past the end of the file (range_not_satisfiable); Content-Range states the size. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 421Another node granted this copy (misdirected). Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 503Storage or the grant record is unavailable; retry (unavailable). Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/copies/v1/<copy_id>/files/<index>' \
    -H 'Authorization: Bookclerk-Copy <token>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/copies/v1/<copy_id>/files/<index>' `
    -Headers @{ Authorization = 'Bookclerk-Copy <token>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/api/copies/v1/<copy_id>/files/<index>",
    headers={"Authorization": "Bookclerk-Copy <token>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/copies/v1/<copy_id>/files/<index>", {
  headers: { Authorization: "Bookclerk-Copy <token>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/api/copies/v1/<copy_id>/files/<index>")
    .header("Authorization", "Bookclerk-Copy <token>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The whole file. The body is binary (application/octet-stream).

Schema:

A application/octet-stream body: binary bytes.

Status 206: The requested byte range, with Content-Range. The body is binary (application/octet-stream).

Schema:

A application/octet-stream body: binary bytes.

Status 401: The copy token is missing, wrong or expired, or the grant no longer holds: the branch is no longer trusted or the library card is signed out, the person may no longer take the edition, or the library's files changed since the grant (unauthorized). Ask for a new grant; a clerk whose library card is signed out signs in again first.

{
  "error": "unauthorized"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 403: The connection failed the transport policy (transport_insecure, with the check in reason).

{
  "error": "transport_insecure",
  "reason": "plain_http"
}

Schema:

{
  "type": "object",
  "description": "JSON body of a `403` from the node API's transport policy: the\nconnection is plain HTTP off loopback, or arrived through a proxy the\npolicy does not trust, and `reason` names the check that refused it.",
  "required": [
    "error",
    "reason"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Always `transport_insecure`.",
      "example": "transport_insecure"
    },
    "reason": {
      "type": "string",
      "description": "The transport check that refused the connection (`plain_http`,\n`unknown_peer`, `untrusted_forwarding`, `proxy_proto_missing`,\n`proxy_proto_ambiguous`, `proxy_proto_not_https`,\n`public_origin_not_https`, `listener_mode_mismatch`,\n`node_api_misconfigured`).",
      "example": "plain_http"
    }
  }
}

Status 404: The index names no file of the copy (unknown_file), or the node API is not mounted on this listener (node_api_unmounted).

{
  "error": "unknown_file"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 416: The range starts at or past the end of the file (range_not_satisfiable); Content-Range states the size.

{
  "error": "range_not_satisfiable"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 421: Another node granted this copy (misdirected).

{
  "error": "misdirected"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 503: Storage or the grant record is unavailable; retry (unavailable).

{
  "error": "unavailable"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

Generated from crates/bookclerkd/openapi.json at main · View as Markdown