Spec

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

Last updated View as Markdown

This document.

Back to the web API reference.

GET /api/openapi.json

Serves the OpenAPI document.

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

Credentials: none

Responses

  • 200The OpenAPI 3.1 document for this daemon's version. Body: OpenApiDocument (application/json)
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/openapi.json'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/openapi.json'
import requests

response = requests.get("http://127.0.0.1:8787/api/openapi.json")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/openapi.json");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/api/openapi.json").await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The OpenAPI 3.1 document for this daemon's version.

{
  "components": {
    "schemas": {}
  },
  "info": {
    "title": "Bookclerk daemon API",
    "version": "0.1.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/health": {
      "get": {
        "responses": {
          "200": {
            "description": "The daemon is up."
          }
        }
      }
    }
  }
}

Schema:

{
  "type": "object",
  "description": "An OpenAPI document as this daemon serves it: the `openapi` version string, `info` about the daemon, every route under `paths` and the schemas under `components`.",
  "examples": [
    {
      "components": {
        "schemas": {}
      },
      "info": {
        "title": "Bookclerk daemon API",
        "version": "0.1.0"
      },
      "openapi": "3.1.0",
      "paths": {
        "/health": {
          "get": {
            "responses": {
              "200": {
                "description": "The daemon is up."
              }
            }
          }
        }
      }
    }
  ]
}

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

request timed out

Schema:

A text/plain body: a string.

GET /api/openapi-3.0.json

Serves the OpenAPI document restated as OpenAPI 3.0.3.

The same API as GET /api/openapi.json, restated in OpenAPI 3.0.3 form for tools that only read 3.0, such as Cloudflare API Shield's schema validation: nullable types use nullable: true, and a nullable reference is a copy of the schema it names.

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

Credentials: none

Responses

  • 200The OpenAPI 3.0.3 document for this daemon's version. Body: OpenApiDocument (application/json)
  • 500The document could not be restated; this is a bug. Body: OpenApiV30Unavailable (application/json)2 fields
    • errorstringrequiredAlways openapi_v30_unavailable.
    • messagestringrequiredWhat to do: the daemon log names the form that could not be restated.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/openapi-3.0.json'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/openapi-3.0.json'
import requests

response = requests.get("http://127.0.0.1:8787/api/openapi-3.0.json")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/openapi-3.0.json");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/api/openapi-3.0.json").await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The OpenAPI 3.0.3 document for this daemon's version.

{
  "components": {
    "schemas": {}
  },
  "info": {
    "title": "Bookclerk daemon API",
    "version": "0.1.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/health": {
      "get": {
        "responses": {
          "200": {
            "description": "The daemon is up."
          }
        }
      }
    }
  }
}

Schema:

{
  "type": "object",
  "description": "An OpenAPI document as this daemon serves it: the `openapi` version string, `info` about the daemon, every route under `paths` and the schemas under `components`.",
  "examples": [
    {
      "components": {
        "schemas": {}
      },
      "info": {
        "title": "Bookclerk daemon API",
        "version": "0.1.0"
      },
      "openapi": "3.1.0",
      "paths": {
        "/health": {
          "get": {
            "responses": {
              "200": {
                "description": "The daemon is up."
              }
            }
          }
        }
      }
    }
  ]
}

Status 500: The document could not be restated; this is a bug.

{
  "error": "openapi_v30_unavailable",
  "message": "The OpenAPI 3.0 document could not be built; see the daemon log."
}

Schema:

{
  "type": "object",
  "description": "Body of the `500` from `GET /api/openapi-3.0.json` when the 3.1\ndocument could not be restated as 3.0.3.",
  "required": [
    "error",
    "message"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Always `openapi_v30_unavailable`.",
      "example": "openapi_v30_unavailable"
    },
    "message": {
      "type": "string",
      "description": "What to do: the daemon log names the form that could not be restated.",
      "example": "The OpenAPI 3.0 document could not be built; see the daemon log."
    }
  }
}

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