openapi.json

{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0.0",
    "title": "TEI Publisher API",
    "description": "This is the core API for TEI Publisher 7. It describes all endpoints used by TEI Publisher web components, plus additional operations added for external access."
  },
  "servers": [
    {
      "description": "Endpoint for testing on localhost",
      "url": "http://localhost:8080/exist/apps/tei-publisher"
    }
  ],
  "tags": [
    {
      "name": "documents",
      "description": "Retrieve document content transformed to target format"
    },
    {
      "name": "DOI",
      "description": "DOI support"
    },
    {
      "name": "collection",
      "description": "Browse the collection hierarchy and upload new files"
    },
    {
      "name": "odd",
      "description": "Manage the ODD files stored in TEI Publisher"
    },
    {
      "name": "search",
      "description": "Searching the collection"
    },
    {
      "name": "transform",
      "description": "Transform content on the fly"
    },
    {
      "name": "view",
      "description": "View documents via an HTML template"
    },
    {
      "name": "apps",
      "description": "Operations to generate/manage apps"
    },
    {
      "name": "dts",
      "description": "Implementation of the DTS (Distributed Text Services) API"
    },
    {
      "name": "info",
      "description": "Information about the server"
    }
  ],
  "components": {
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic"
      },
      "cookieAuth": {
        "type": "apiKey",
        "name": "teipublisher.com.login",
        "in": "cookie"
      },
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "paths": {
    "/{file}.html": {
      "get": {
        "summary": "Retrieve HTML page",
        "description": "Retrieve an HTML page expanded through eXist templating. This is used to load the top-level HTML pages, e.g. `index.html`.",
        "tags": [
          "view"
        ],
        "operationId": "vapi:html",
        "x-error-handler": "vapi:handle-error",
        "parameters": [
          {
            "name": "file",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTML of the page",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "The document was not found",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/{doc}": {
      "get": {
        "summary": "Retrieve the HTML template used for displaying a document",
        "description": "Get the HTML template associated with the given document. This is called whenever the users tries to view a document. The actual content of the document will then be loaded by the template.",
        "tags": [
          "view"
        ],
        "operationId": "vapi:view",
        "x-error-handler": "vapi:handle-error",
        "parameters": [
          {
            "name": "doc",
            "in": "path",
            "description": "Relative path to the document",
            "required": true,
            "schema": {
              "type": "string",
              "example": "test/orlik_to_serafin.xml"
            },
            "allowReserved": true
          },
          {
            "name": "template",
            "in": "query",
            "description": "Name of the template to be used. Overwrites any default template setting.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "view",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "page",
                "div",
                "single"
              ]
            },
            "example": "div",
            "description": "The view type used by the main view which displays the document, e.g. 'page' or 'div'. This has an influence on the generated links, which need to differ when linking to a page rather than a section."
          },
          {
            "name": "odd",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "action",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTML view for the document",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "The document was not found",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/version": {
      "get": {
        "summary": "Get version information about this service",
        "description": "Get the version of TEI Publisher running this service as well as the API version implemented",
        "operationId": "iapi:version",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "tags": [
          "info"
        ],
        "responses": {
          "200": {
            "description": "Version information about this service",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "api": {
                      "type": "string"
                    },
                    "app": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "version": {
                          "type": "string"
                        }
                      }
                    },
                    "engine": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "version": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/collection/{path}": {
      "get": {
        "summary": "Get formatted overview of documents in the collection",
        "tags": [
          "collection"
        ],
        "operationId": "capi:list",
        "parameters": [
          {
            "name": "path",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "test"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns HTML describing the collection",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/collection": {
      "get": {
        "summary": "Get formatted overview of documents in the collection",
        "tags": [
          "collection"
        ],
        "operationId": "capi:list",
        "responses": {
          "200": {
            "description": "Returns HTML describing the collection",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/upload": {
      "post": {
        "summary": "Upload a number of files to the top-level data collection of the app",
        "tags": [
          "collection"
        ],
        "operationId": "capi:upload",
        "x-constraints": {
          "group": "tei"
        },
        "parameters": [
          {
            "name": "content-Length",
            "in": "header",
            "schema": {
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "files[]": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "binary"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Upload response",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "path": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string"
                    },
                    "size": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "description": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Upload collection not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "500": {
            "description": "Upload collection not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/upload/{collection}": {
      "post": {
        "summary": "Upload a number of files",
        "tags": [
          "collection"
        ],
        "operationId": "capi:upload",
        "x-constraints": {
          "group": "tei"
        },
        "parameters": [
          {
            "name": "content-Length",
            "in": "header",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "collection",
            "in": "path",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "files[]": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "binary"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Upload response",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "path": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string"
                    },
                    "size": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "description": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Upload collection not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "500": {
            "description": "Upload collection not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/doi/upload": {
      "post": {
        "summary": "Upload a number of files to the top-level data collection of the app and creating a DOI for them.",
        "tags": [
          "DOI"
        ],
        "operationId": "capi:uploadDOI",
        "x-constraints": {
          "group": "tei"
        },
        "parameters": [
          {
            "name": "content-Length",
            "in": "header",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "availability",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "files[]": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "binary"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Upload response",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "path": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string"
                    },
                    "size": {
                      "type": "number"
                    },
                    "doi": {
                      "type": "string"
                    },
                    "doi-detail": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "description": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Upload collection not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "500": {
            "description": "Upload collection not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/doi/upload/{collection}": {
      "post": {
        "summary": "Upload a number of files",
        "tags": [
          "DOI"
        ],
        "operationId": "capi:upload",
        "x-constraints": {
          "group": "tei"
        },
        "parameters": [
          {
            "name": "collection",
            "in": "path",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "name": "availability",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "files[]": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "binary"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Upload response",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "path": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string"
                    },
                    "size": {
                      "type": "number"
                    },
                    "doi": {
                      "type": "string"
                    },
                    "doi-detail": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "description": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Upload collection not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "500": {
            "description": "Upload collection not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/document/{id}": {
      "delete": {
        "summary": "Delete a document",
        "tags": [
          "documents"
        ],
        "operationId": "dapi:delete",
        "x-constraints": {
          "group": "tei"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "410": {
            "description": "Document deleted"
          }
        }
      }
    },
    "/api/document/{id}/html": {
      "get": {
        "summary": "Retrieve document content as HTML",
        "description": "Retrieve whole document transformed to HTML via ODD",
        "tags": [
          "documents"
        ],
        "operationId": "dapi:html",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "test/F-rom.xml"
            }
          },
          {
            "name": "odd",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "shakespeare.odd"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns the entire document as HTML",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Document not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/document/{id}/pdf": {
      "get": {
        "summary": "Retrieve document content as PDF",
        "description": "Retrieve whole document transformed via ODD and FO",
        "tags": [
          "documents"
        ],
        "operationId": "dapi:pdf",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "test/F-rom.xml"
            },
            "description": "Path to the XML document"
          },
          {
            "name": "source",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Set to true to see generated XML FO source"
          },
          {
            "name": "token",
            "in": "query",
            "schema": {
              "type": "string",
              "nullable": true
            }
          },
          {
            "name": "cache",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns a PDF",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Document not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/document/{id}/tex": {
      "get": {
        "summary": "Retrieve document content as PDF",
        "description": "Retrieve whole document transformed via ODD and LaTeX",
        "tags": [
          "documents"
        ],
        "operationId": "dapi:latex",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "test/F-rom.xml"
            }
          },
          {
            "name": "source",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns a PDF",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/x-latex": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Document not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/document/{id}/epub": {
      "get": {
        "summary": "Retrieve document content as EPub",
        "description": "Retrieve whole document as EPub transformed via ODD",
        "tags": [
          "documents"
        ],
        "operationId": "dapi:epub",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "doc/documentation.xml"
            }
          },
          {
            "name": "token",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "odd",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "docbook.odd"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns an ePUB",
            "content": {
              "application/epub+zip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "Document not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/document/{id}/contents": {
      "get": {
        "summary": "Retrieve a formatted table of contents for the document",
        "description": "Retrieve a formatted table of contents for the document, transformed via ODD",
        "tags": [
          "documents"
        ],
        "operationId": "dapi:table-of-contents",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "test/kant_rvernunft_1781.TEI-P5.xml"
            }
          },
          {
            "name": "odd",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "teipublisher.odd"
            }
          },
          {
            "name": "view",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "page",
                "div",
                "single"
              ]
            },
            "example": "div",
            "description": "The view type used by the main view which displays the document, e.g. 'page' or 'div'. This has an influence on the generated links, which need to differ when linking to a page rather than a section."
          },
          {
            "name": "target",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "The target channel into which link selection events should be send (if the user clicks on a link)"
          },
          {
            "name": "icons",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": true
            },
            "description": "Should an expand/collapse icon be displayed next to headings having nested child sections?"
          }
        ],
        "responses": {
          "200": {
            "description": "Returns the formatted table of contents as HTML",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Document not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/parts/{doc}/{format}": {
      "get": {
        "summary": "Retrieve parts of a document transformed via ODD",
        "description": "Retrieve a document fragment, usually a division or page, transformed to HTML via the ODD. This operation is internally used by pb-view, but can also be helpful with pb-load or in other contexts.",
        "operationId": "dapi:get-fragment",
        "tags": [
          "documents"
        ],
        "parameters": [
          {
            "name": "doc",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "doc/documentation.xml",
            "description": "path to the document, relative to TEI Publisher's data root colletion"
          },
          {
            "name": "format",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "html"
              ]
            },
            "description": "the format to return: either `json` or `html`. The first returns the HTML inside a JSON record with additional information about the next/previous page and so on. The latter is mainly for debugging purposes."
          },
          {
            "name": "odd",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "shakespeare.odd"
            }
          },
          {
            "name": "view",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "page",
                "div",
                "single"
              ]
            },
            "example": "div",
            "description": "the view to use: this determines the size of the fragment returned, i.e. just a page, a whole division or the entire document"
          },
          {
            "name": "root",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "an eXist node id used to identify the root of the fragment to return. mainly used to navigate to the next/previous fragment based on the properties received in the JSON record during a preceding request."
          },
          {
            "name": "id",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "an xml:id to load: can be used instead of `root` to determine the fragment root to be loaded. Should be an xml:id existing in the document."
          },
          {
            "name": "xpath",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "an XPath expression to directly select a sub-part of the document, e.g. the TEI body, front or back matter, or teiHeader. Usually only makes sense in combination with `view=single`."
          },
          {
            "name": "map",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "defines an optional mapping function (written in XQuery), which can be used to replace the document content to be processed with something else. Used to e.g. look up the translation for a given transcription and process it instead."
          },
          {
            "name": "highlight",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "view": {
                      "type": "string",
                      "description": "the view type used"
                    },
                    "doc": {
                      "type": "string",
                      "description": "path to the document from which the fragment was retrieved"
                    },
                    "root": {
                      "type": "string",
                      "nullable": true
                    },
                    "odd": {
                      "type": "string",
                      "description": "the ODD used for the transformation"
                    },
                    "next": {
                      "type": "string",
                      "nullable": true,
                      "description": "points to the next fragment in the document. Pass this value as `root` in a follow up request."
                    },
                    "previous": {
                      "type": "string",
                      "nullable": true,
                      "description": "points to the previous fragment in the document. Pass this value as `root` in a follow up request."
                    },
                    "switchView": {
                      "type": "string",
                      "nullable": true
                    },
                    "content": {
                      "type": "string",
                      "description": "the content of the fragment as HTML string"
                    },
                    "footnotes": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Document not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/odd/{odd}": {
      "get": {
        "summary": "Retrieve an ODD",
        "description": "Retrieve an ODD as TEI/XML",
        "tags": [
          "odd"
        ],
        "operationId": "oapi:get-odd",
        "parameters": [
          {
            "name": "odd",
            "in": "path",
            "description": "Filename of the ODD including suffix (.odd)",
            "schema": {
              "type": "string",
              "example": "docbook.odd"
            },
            "required": true
          },
          {
            "name": "ident",
            "in": "query",
            "description": "Only return the elementSpec matching this ident. If set, response will be in JSON format.",
            "schema": {
              "type": "string",
              "nullable": true
            }
          },
          {
            "name": "root",
            "in": "query",
            "description": "Context path against which the the ODD path will be resolved. Used by ODD editor.",
            "schema": {
              "type": "string",
              "nullable": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns the TEI/XML source of the ODD",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "ODD not found"
          }
        }
      },
      "delete": {
        "summary": "Delete an ODD from the database",
        "description": "Delete the ODD given in the path parameter from the database. The ODD should be located in the collection referenced by `config:odd-root` in `modules/config.xqm`.",
        "tags": [
          "odd"
        ],
        "operationId": "oapi:delete-odd",
        "x-constraints": {
          "group": "tei"
        },
        "parameters": [
          {
            "name": "odd",
            "in": "path",
            "schema": {
              "type": "string",
              "example": "testodd.odd"
            },
            "description": "Filename of the ODD including suffix (.odd)",
            "required": true
          }
        ],
        "responses": {
          "404": {
            "description": "ODD not found"
          },
          "410": {
            "description": "ODD was deleted"
          }
        }
      },
      "post": {
        "summary": "Create an ODD",
        "description": "Create a new ODD using the file name given in the path",
        "tags": [
          "odd"
        ],
        "operationId": "oapi:create-odd",
        "x-constraints": {
          "group": "tei"
        },
        "parameters": [
          {
            "name": "odd",
            "in": "path",
            "schema": {
              "type": "string"
            },
            "description": "Filename of the ODD without suffix (.odd)",
            "required": true
          },
          {
            "name": "title",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "responses": {
          "201": {
            "description": "ODD was created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "path": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Save ODD",
        "description": "Replace an ODD with the current version from the editor",
        "tags": [
          "odd"
        ],
        "operationId": "oapi:save-odd",
        "x-constraints": {
          "group": "tei"
        },
        "parameters": [
          {
            "name": "odd",
            "in": "path",
            "schema": {
              "type": "string",
              "example": "testodd.odd"
            },
            "description": "Filename of the ODD with the suffix (.odd)",
            "required": true
          },
          {
            "name": "root",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "/db/apps/tei-publisher/odd"
            },
            "description": "Collection into which the ODD should be written"
          },
          {
            "name": "output-root",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "/db/apps/tei-publisher/transform"
            },
            "description": "The collection into which generated code files will be written"
          },
          {
            "name": "output-prefix",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "transform"
            },
            "description": "Relative path (from app root) used for resolving connected CSS files"
          }
        ],
        "requestBody": {
          "content": {
            "application/xml": {
              "schema": {
                "type": "string"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "ODD was saved",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "path": {
                      "type": "string"
                    },
                    "report": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/odd": {
      "get": {
        "summary": "Get a list of ODDs available",
        "operationId": "oapi:list-odds",
        "tags": [
          "odd"
        ],
        "responses": {
          "200": {
            "description": "Ok",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "label": {
                        "type": "string"
                      },
                      "description": {
                        "type": "string",
                        "nullable": true
                      },
                      "path": {
                        "type": "string"
                      },
                      "canWrite": {
                        "type": "boolean"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Recompile ODDs",
        "description": "Recompile one or more ODDs after they were changed",
        "operationId": "oapi:recompile",
        "tags": [
          "odd"
        ],
        "x-constraints": {
          "group": "tei"
        },
        "parameters": [
          {
            "name": "odd",
            "in": "query",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          {
            "name": "check",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Run additional check to ensure the generated code is valid and compiles"
          }
        ],
        "responses": {
          "200": {
            "description": "ODDs were recompiled. The result of the compilation is returned as HTML.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/lint": {
      "post": {
        "summary": "Check an XPath/XQuery snippet",
        "description": "Check an XPath/XQuery snippet used in an ODD for syntactical correctness (called by ODD editor)",
        "operationId": "oapi:lint",
        "tags": [
          "odd"
        ],
        "parameters": [
          {
            "name": "code",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "starts-with(., 'f')"
            },
            "description": "Code snippet",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/templates": {
      "get": {
        "summary": "List available HTML templates",
        "description": "Lists all page layout templates available for the document view. Used by `pb-select-templates`.",
        "tags": [
          "view"
        ],
        "operationId": "iapi:list-templates",
        "responses": {
          "200": {
            "description": "Array of templates",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "title": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/search": {
      "get": {
        "summary": "Run a search on all TEI Publisher collections",
        "operationId": "sapi:search",
        "tags": [
          "search"
        ],
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "description": "Query string",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "field",
            "in": "query",
            "description": "The field to query",
            "schema": {
              "type": "string",
              "default": "text"
            }
          },
          {
            "name": "start",
            "in": "query",
            "description": "Start offset of the first item to show from the result set",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "per-page",
            "in": "query",
            "description": "Number of items to show on one page",
            "schema": {
              "type": "integer",
              "default": 10
            }
          },
          {
            "name": "doc",
            "in": "query",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "nullable": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results returned",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/search/facets": {
      "get": {
        "summary": "List facets",
        "description": "Return a list of facet counts for current search results",
        "operationId": "sapi:facets",
        "tags": [
          "search"
        ],
        "responses": {
          "200": {
            "description": "Facets returned",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/search/autocomplete": {
      "get": {
        "summary": "List possible completions",
        "description": "Return a list of possible completions for the given search term",
        "operationId": "sapi:autocomplete",
        "tags": [
          "search"
        ],
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "description": "The prefix to expand",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "name": "field",
            "in": "query",
            "description": "The field to query",
            "schema": {
              "title": "string",
              "default": "text"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of possible completions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "text": {
                        "type": "string"
                      },
                      "value": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/convert": {
      "post": {
        "summary": "Convert a Word document to TEI/XML",
        "tags": [
          "transform"
        ],
        "operationId": "dapi:convert-docx",
        "parameters": [
          {
            "name": "odd",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "docx.odd"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/xml": {
              "schema": {
                "type": "string"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resulting TEI/XML output",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/preview": {
      "post": {
        "summary": "Post an XML document and get a preview rendered via ODD",
        "tags": [
          "transform"
        ],
        "operationId": "dapi:preview",
        "parameters": [
          {
            "name": "odd",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/xml": {
              "schema": {
                "type": "string"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resulting HTML output",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/login": {
      "post": {
        "summary": "Login the user",
        "description": "Login the given user",
        "tags": [
          "user"
        ],
        "operationId": "rutil:login",
        "parameters": [
          {
            "name": "user",
            "in": "query",
            "description": "Name of the user",
            "schema": {
              "type": "string",
              "example": "tei",
              "nullable": true
            }
          },
          {
            "name": "password",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "password",
              "example": "simple",
              "nullable": true
            }
          },
          {
            "name": "logout",
            "in": "query",
            "description": "Set to some value to log out the current user",
            "schema": {
              "type": "string",
              "nullable": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "user": {
                      "type": "string"
                    },
                    "groups": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "dba": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Wrong user or password"
          }
        }
      }
    },
    "/api/apps/download": {
      "get": {
        "summary": "Package and download app",
        "description": "Package up this application and return it as a `.xar`.",
        "tags": [
          "apps"
        ],
        "operationId": "deploy:download-app",
        "responses": {
          "200": {
            "description": "xar package (zip format) containing the app code",
            "content": {
              "application/zip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          }
        }
      }
    },
    "/api/apps/generate": {
      "post": {
        "summary": "Generate a TEI-Publisher stand-alone application",
        "description": "Generate a stand-alone application based on an ODD, template and other settings",
        "tags": [
          "apps"
        ],
        "operationId": "deploy:generate",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "odd": {
                    "type": "array",
                    "description": "One or more ODDs to include in the app",
                    "items": {
                      "type": "string"
                    }
                  },
                  "uri": {
                    "type": "string"
                  },
                  "abbrev": {
                    "type": "string"
                  },
                  "title": {
                    "type": "string"
                  },
                  "data-collection": {
                    "type": "string",
                    "nullable": true
                  },
                  "template": {
                    "type": "string"
                  },
                  "default-view": {
                    "type": "string",
                    "enum": [
                      "div",
                      "page"
                    ]
                  },
                  "index": {
                    "type": "string",
                    "enum": [
                      "tei:div",
                      "tei:text"
                    ]
                  },
                  "owner": {
                    "type": "string"
                  },
                  "password": {
                    "type": "string",
                    "format": "password"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "App generated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "target": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "App already exists"
          },
          "500": {
            "description": "Generation failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "description": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "nullable": true
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/dts": {
      "get": {
        "summary": "Base API endpoint",
        "description": "Returns the base path for the 3 endpoints: collection, navigation and documents",
        "operationId": "dts:base-endpoint",
        "tags": [
          "dts"
        ],
        "responses": {
          "200": {
            "description": "Server configuration information",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "@context": {
                      "type": "string",
                      "nullable": false
                    },
                    "@id": {
                      "type": "string",
                      "nullable": false
                    },
                    "@type": {
                      "type": "string",
                      "nullable": false
                    },
                    "collection": {
                      "type": "string",
                      "nullable": false
                    },
                    "documents": {
                      "type": "string",
                      "nullable": false
                    },
                    "navigation": {
                      "type": "string",
                      "nullable": false
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/dts/collection": {
      "get": {
        "summary": "Navigate collection",
        "description": "The collections endpoint is used for navigating collections. A collection contains metadata for the collection itself and an array of members. Each member is either a collection or the metadata for a document.",
        "operationId": "dts:collection",
        "tags": [
          "dts"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Collection metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/dts/document": {
      "get": {
        "summary": "Document endpoint",
        "description": "The Document endpoint is used to access and modify the content of document, as opposed to metadata (which is found in collections).",
        "operationId": "dts:documents",
        "tags": [
          "dts"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "TEI/XML of the document",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/dts/import": {
      "get": {
        "summary": "Import a remote resource into local database",
        "description": "Helper operation to import a remote resource, optionally into a temporary collection",
        "tags": [
          "dts"
        ],
        "operationId": "dts:import",
        "x-constraints": {
          "group": "tei"
        },
        "parameters": [
          {
            "name": "uri",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "name": "temp",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Content was successfully imported",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "path": {
                      "type": "string",
                      "nullable": false
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "cookieAuth": []
    },
    {
      "basicAuth": []
    },
    {
      "bearerAuth": []
    }
  ]
}