{
  "openapi": "3.0.3",
  "info": {
    "title": "AB",
    "description": "AB knows all books. Search and metadata API. Metadata sourced from Project Gutenberg and Open Library -- public-domain/openly-licensed sources only.",
    "version": "0.1.0",
    "contact": { "email": "abuse@all.books.party" }
  },
  "paths": {
    "/api/search": {
      "get": {
        "summary": "Search books by title or author",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 } }
        ],
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SearchResponse" }
              }
            }
          }
        }
      }
    },
    "/api/books/{id}": {
      "get": {
        "summary": "Get a single book plus its identifiers",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": {
            "description": "Book detail",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Book" }
              }
            }
          },
          "404": { "description": "No book with that id" }
        }
      }
    },
    "/api/books/{id}/download": {
      "get": {
        "summary": "Redirect to the book's file at its source, if the source's files are freely redistributable",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": {
          "302": { "description": "Redirect to the file" },
          "404": { "description": "No book with that id, or no downloadable file known for its source" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Identifier": {
        "type": "object",
        "properties": {
          "type": { "type": "string", "example": "gutenberg_id" },
          "value": { "type": "string", "example": "1661" }
        }
      },
      "Book": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "source": { "type": "string", "example": "gutenberg" },
          "source_native_id": { "type": "string", "nullable": true },
          "title": { "type": "string", "nullable": true },
          "authors": { "type": "string", "nullable": true },
          "language": { "type": "string", "nullable": true },
          "subjects": { "type": "array", "items": { "type": "string" } },
          "bookshelves": { "type": "array", "items": { "type": "string" } },
          "issued": { "type": "string", "nullable": true },
          "type": { "type": "string", "nullable": true },
          "identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/Identifier" } }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "count": { "type": "integer" },
          "results": { "type": "array", "items": { "$ref": "#/components/schemas/Book" } }
        }
      }
    }
  }
}