{ "openapi": "3.0.3", "info": { "version": "1.0.0", "title": "TEI Publisher Documentation and Demo", "description": "This is the core API for TEI Publisher. 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": "/exist/apps/tei-publisher" } ], "tags": [ { "name": "documents", "description": "Retrieve document content transformed to target format" }, { "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": "info", "description": "Information about the server" }, { "name": "register", "description": "Manage entries in the local authority file" }, { "name": "nlp", "description": "Entity recognition and other natural language processing features" }, { "name": "annotations", "description": "Endpoints for the annotation editor" }, { "name": "actions", "description": "Action endpoints to be called by jinks" } ], "components": { "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" }, "cookieAuth": { "type": "apiKey", "name": "teipublisher.com.login", "in": "cookie" } } }, "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", "description": "Path to the document relative to the `template` collection below the application root", "required": true, "schema": { "type": "string" } }, { "name": "lang", "in": "query", "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" } } } } } } }, "/{docid}": { "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": "docid", "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" } } } }, "500": { "description": "An error occurred", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/print/{docid}": { "get": { "summary": "Generate a print preview using Paged Media CSS", "tags": ["view"], "operationId": "vapi:view", "x-error-handler": "vapi:handle-error", "parameters": [ { "name": "docid", "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", "default": "print-preview.html" } }, { "name": "odd", "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" } } } }, "500": { "description": "An error occurred", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/{file}.md": { "get": { "summary": "Retrieve the HTML template for a markdown file and render it", "description": "Get the HTML template associated with the given markdown document. This is called whenever the users tries to view a markdown file. The actual content of the document will then be loaded by the template.", "tags": ["view"], "operationId": "vapi:text", "x-error-handler": "vapi:handle-error", "parameters": [ { "name": "file", "in": "path", "description": "Relative path to the document", "required": true, "schema": { "type": "string", "example": "markdown.md" }, "allowReserved": true }, { "name": "suffix", "in": "query", "schema": { "type": "string", "default": ".md" } } ], "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" } } } }, "500": { "description": "An error occurred", "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", "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" } }, { "name": "start", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per-page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 10 } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["html", "json"], "default": "html" } }, { "name": "language", "in": "query", "schema": { "type": "string", "default": "en" } }, { "name": "query", "in": "query", "schema": { "type": "string" } }, { "name": "field", "in": "query", "schema": { "type": "string" } } ], "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", "parameters": [ { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["html", "json"], "default": "html" } }, { "name": "start", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per-page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 10 } }, { "name": "query", "in": "query", "schema": { "type": "string" } }, { "name": "field", "in": "query", "schema": { "type": "string" } }, { "name": "language", "in": "query", "schema": { "type": "string", "default": "en" } } ], "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": { "groups": ["tei"] }, "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": { "groups": ["tei"] }, "parameters": [ { "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/documents": { "get": { "summary": "List documents", "description": "Retrieve list of documents in a collection", "tags": ["collection"], "operationId": "capi:documents", "parameters": [ { "name": "link", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "array with each member describing a document", "content": { "application/json": { "schema": { "type": "array" } } } } } } }, "/api/documents/{path}": { "get": { "summary": "List documents", "description": "Retrieve list of documents in a collection", "tags": ["collection"], "operationId": "capi:documents", "parameters": [ { "name": "path", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "link", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "array with each member describing a document", "content": { "application/json": { "schema": { "type": "array" } } } } } } }, "/api/document/{id}": { "get": { "summary": "Get the source of a document", "description": "Get the source of a document, either as XML, text or binary.", "tags": ["documents"], "operationId": "dapi:source", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Content of the document", "content": { "application/xml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/text": { "schema": { "type": "string" } } } }, "410": { "description": "Document deleted" } } }, "delete": { "summary": "Delete a document", "tags": ["documents"], "operationId": "dapi:delete", "x-constraints": { "groups": ["tei"] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "410": { "description": "Document deleted" } } }, "put": { "summary": "Update the document", "description": "Update the document", "tags": ["documents"], "operationId": "dapi:save", "requestBody": { "content": { "application/xml": { "schema": { "type": "string" } } } }, "parameters": [ { "name": "id", "in": "path", "description": "path to the document", "required": true, "schema": { "type": "string" } }, { "name": "create", "in": "query", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/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" } }, { "name": "base", "description": "Base URI to use", "in": "query", "schema": { "type": "string" } }, { "name": "wc", "description": "Include TEI Publisher webcomponents", "in": "query", "schema": { "type": "boolean", "default": true } } ], "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}/print": { "get": { "summary": "Retrieve document content as HTML optimized for Print CSS", "tags": ["documents"], "operationId": "dapi:print", "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" } }, { "name": "base", "description": "Base URI to use for resolving links and images", "in": "query", "schema": { "type": "string" } }, { "name": "wc", "description": "Include TEI Publisher webcomponents if set. 'page' will also inject a wrapper if not present, using parameter 'base' as endpoint.", "in": "query", "schema": { "type": "string" } }, { "name": "style", "description": "Additional CSS stylesheet URLs to be loaded", "in": "query", "style": "form", "schema": { "type": "array", "items": { "type": "string" } } }, { "description": "Additional script URLs to be loaded", "name": "script", "in": "query", "style": "form", "schema": { "type": "array", "items": { "type": "string" } } } ], "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}/md": { "get": { "summary": "Retrieve document content as markdown", "tags": [ "documents" ], "operationId": "dapi:markdown", "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" } }, { "name": "base", "description": "Base URI to use for resolving links and images", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the entire document as markdown", "content": { "text/markdown": { "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", "x-error-handler": "vapi:handle-error", "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" } } } }, "400": { "description": "LaTeX processing failed", "content": { "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "Internal server error", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/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" } }, { "name": "images-collection", "in": "query", "schema": { "type": "string", "example": "/apps/tei-publisher/data" } }, { "name": "skip-title", "in": "query", "schema": { "type": "boolean", "example": "true" } }, { "name": "cover-image", "in": "query", "schema": { "type": "string", "example": "images/cover.jpg" } } ], "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}/meta": { "get": { "summary": "Returns some metadata about the document", "tags": ["documents"], "operationId": "dapi:metadata", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "test/kant_rvernunft_1781.TEI-P5.xml" } } ], "responses": { "200": { "description": "Metadata about the document as JSON object", "content": { "application/json": { "schema": { "type": "object" } } } }, "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": "collapse", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the table of contents will be collapsed" }, { "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?" }, { "name": "If-Modified-Since", "in": "header", "schema": { "type": "string" } } ], "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" } }, { "name": "serialize", "in": "query", "schema": { "type": "string", "enum": ["xml", "html5"], "default": "html5" }, "description": "should HTML content be rendered as HTML5 or XML?" }, { "name": "wrap", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "should returned HTML be wrapped into a div?" }, { "name": "If-Modified-Since", "in": "header", "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": { "groups": ["tei"] }, "parameters": [ { "name": "odd", "in": "path", "schema": { "type": "string", "example": "testodd.odd" }, "description": "Filename of the ODD including suffix (.odd)", "required": true } ], "responses": { "410": { "description": "ODD was deleted" }, "404": { "description": "ODD not found" } } }, "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": { "groups": ["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": { "groups": ["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" }, "source": { "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": { "groups": ["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", "nullable": true } } } } } } } } } }, "/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/facets/{type}": { "get": { "summary": "List facet values occurring in current search result set", "operationId": "sapi:list-facets", "tags": ["search"], "parameters": [ { "name": "query", "in": "query", "description": "Query string to filter facets by", "schema": { "type": "string" } }, { "name": "language", "in": "query", "schema":{ "type": "string", "default": "en" } }, { "name": "type", "in": "path", "description": "The facet type, e.g. 'place' or 'person'", "required": true, "schema": { "type": "string", "example": "place" } } ], "responses": { "200": { "description": "Facets returned", "content": { "application/json": { "schema": { "type": "array" } } } } } } }, "/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" } }, { "name": "base", "description": "Base URI to use for the HTML document", "in": "query", "schema": { "type": "string" } }, { "name": "wc", "description": "Include TEI Publisher webcomponents", "in": "query", "schema": { "type": "boolean", "default": true } } ], "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": "auth:login", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "nullable": true, "properties": { "user": { "description": "Name of the user", "type": "string" }, "password": { "type": "string", "format": "password" } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "nullable": true, "properties": { "user": { "description": "Name of the user", "type": "string" }, "password": { "type": "string", "format": "password" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "string" }, "groups": { "type": "array", "items": { "type": "string" } }, "dba": { "type": "boolean" }, "domain": { "type": "string" } } } } } }, "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/nlp/entities/{id}": { "get": { "summary": "Call entity extraction on a document or collection of documents", "operationId": "nlp:entity-recognition", "tags": ["nlp"], "parameters": [ { "name": "id", "in": "path", "description": "Relative path to collection or single document", "schema": { "type": "string" }, "required": true }, { "name": "model", "in": "query", "schema": { "type": "string", "example": "en_core_web_sm" }, "required": true }, { "name": "debug", "in": "query", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "JSON structure listing the entities found", "content": { "application/json": { "schema": { "type": "array" } } } } } } }, "/api/nlp/patterns/{id}": { "get": { "summary": "Apply rule-based pattern matching", "description": "Use rule-based pattern matching to find entities in a document", "operationId": "nlp:pattern-recognition", "tags": ["nlp"], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true }, { "name": "lang", "in": "query", "schema": { "type": "string", "default": "en" } }, { "name": "debug", "in": "query", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "JSON structure listing the entities found", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/nlp/strings/{id}": { "get": { "summary": "Find occurrences of the given string in other documents in the collection", "operationId": "nlp:strings", "tags": ["nlp"], "parameters": [ { "name": "id", "in": "path", "description": "Relative path to collection", "schema": { "type": "string" }, "required": true }, { "name": "format", "in": "query", "description": "Format of the JSON structure to return", "schema": { "type": "string", "enum": [ "offsets", "annotations" ], "default": "annotations" } }, { "name": "string", "in": "query", "schema": { "type": "string" }, "required": true }, { "name": "type", "in": "query", "schema": { "type": "string" }, "required": true }, { "name": "properties", "in": "query", "schema": { "type": "string" } }, { "name": "exclude", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON structure listing the entities found", "content": { "application/json": { "schema": { "type": "array" } } } } } } }, "/api/nlp/strings": { "post": { "summary": "Find occurrences of the given string in other documents in the collection", "operationId": "nlp:matches-to-annotations", "tags": ["nlp"], "requestBody":{ "description": "List of matches as returned by a GET with format=offsets", "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "JSON structure listing the entities found", "content": { "application/json": { "schema": { "type": "array" } } } } } } }, "/api/nlp/text/{id}": { "get": { "summary": "Retrieve plain text of a document", "description": "Get the plain text of the given document fragment to be fed into entity recognition", "operationId": "nlp:plain-text", "tags": ["nlp"], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Plain text of the document fragment", "content": { "text/text": { "schema": { "type": "string" } } } } } } }, "/api/nlp/status": { "get": { "summary": "Return status information about NER", "description": "Return status information about NER, including installed pipelines", "tags": ["nlp"], "operationId": "nlp:status", "responses": { "200": { "description": "JSON object describing status", "content": { "application/json":{ "schema": { "type": "object" } } } } } } }, "/api/nlp/status/models": { "get": { "summary": "Return list of available models", "tags": ["nlp"], "operationId": "nlp:models", "responses": { "200": { "description": "JSON array listing models", "content": { "application/json":{ "schema": { "type": "array" } } } } } } }, "/api/nlp/train/{id}": { "get": { "summary": "Train an NER model", "description": "Train an NER model based on training data, which will be generated from a given document or collection", "tags": ["nlp"], "operationId": "nlp:train-model", "parameters": [ { "name": "id", "in": "path", "description": "Relative path to document or collection", "schema": { "type": "string" }, "required": true }, { "name": "name", "in": "query", "description": "Name of the model to create", "schema": { "type": "string" }, "required": true }, { "name": "base", "in": "query", "description": "Base model to extend", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "description": "Language to create the model for", "schema": { "type": "string" } }, { "name": "copy_vectors", "in": "query", "description": "Base model to copy vector layer from", "schema":{ "type": "string" } } ], "responses": { "200": { "description": "Process ID of the running training", "content": { "application/json":{ "schema": { "type": "integer" } } } } } } }, "/api/nlp/log/{pid}": { "get": { "summary": "Return log messages for an ongoing training", "tags": ["nlp"], "operationId": "nlp:log", "parameters": [ { "name": "pid", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Training completed", "content": { "text/text":{ "schema": { "type": "string" } } } }, "202": { "description": "Training in progress", "content": { "text/text":{ "schema": { "type": "string" } } } } } } }, "/api/nlp/data/{id}": { "get": { "summary": "Download training data for NER", "description": "Generate training data for NER from a given document or collection", "tags": ["nlp"], "operationId": "nlp:train", "parameters": [ { "name": "id", "in": "path", "description": "Relative path to document or collection", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "JSON array with training data", "content": { "application/json":{ "schema": { "type": "array" } } } } } } }, "/api/forms/template/{id}": { "get": { "summary": "Retrieve XML template document to be used as a form instance", "description": "Retrieve whole document as XML", "tags": [ "annotations" ], "operationId": "rapi:form-template", "x-constraints": { "group": "tei" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "person-template" } } ], "responses": { "200": { "description": "Returns the entire form instance template as XML", "content": { "application/xml": { "schema": { "type": "string" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/register/search/{type}" : { "get": { "summary": "Search for a register entry", "operationId": "rapi:query-register", "tags": ["register"], "parameters": [ { "name": "type", "in": "path", "schema": { "type": "string" }, "required": true, "example": "place" }, { "name": "query", "in": "query", "schema": { "type": "string" }, "required": true, "example": "Deya" } ], "responses": { "200": { "description": "Results from the local register", "content": { "application/json": { "schema": { "type": "array" } } } } } } }, "/api/register/{type}/{id}" : { "post": { "summary": "Create a copy of an authority record in the local register", "description": "Create a copy of an authority record in the local register based on the passed JSON structure. Used by the custom authority connector.", "tags": ["register"], "operationId": "rapi:save-local-copy", "requestBody": { "description": "JSON record providing base information for the entry", "content": { "application/json": { "schema": { "type": "object" } } } }, "parameters": [ { "name": "type", "in": "path", "schema": { "type": "string" }, "required": true, "example": "place" }, { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true, "example": "Deia" } ], "responses": { "200": { "description": "Results from the local register", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "get": { "summary": "Retrieve JSON-formatted authority record from the local register", "description": "Used by the custom authority connector.", "operationId": "rapi:register-entry", "tags": ["register"], "parameters": [ { "name": "type", "in": "path", "schema": { "type": "string" }, "required": true, "example": "place" }, { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true, "example": "Deia" }, { "name": "format", "in": "query", "schema": { "type": "string", "default": "json" } } ], "responses": { "200": { "description": "Results from the local register", "content": { "application/json": { "schema": { "type": "object" } }, "application/xml": { "schema": { "type": "string" } } } } } } }, "/api/register": { "put": { "summary": "Save a new register entry", "description": "The type is determined by the passed TEI element", "tags": ["register"], "operationId": "rapi:save", "x-constraints": { "group": ["tei"] }, "requestBody": { "content": { "application/xml": { "schema": { "type": "string" } } } }, "responses": { "201": { "description": "Entry was saved", "content": { "application/xml": { "schema": { "type": "string" } } } }, "401": { "description": "Permission denied", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/register/{id}": { "get": { "summary": "Retrieve XML for a given register entry", "description": "Get the XML fragment for a given register entry. Used by the registry forms in the annotation editor.", "tags": ["register"], "operationId": "rapi:entry", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "gnd-139890289" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "example": "place", "default": "person" } } ], "responses": { "200": { "description": "Returns the entire entry as XML", "content": { "application/xml": { "schema": { "type": "string" } } } }, "404": { "description": "Entry id not found", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "delete": { "summary": "Delete an entry from the register", "tags": ["register"], "operationId": "rapi:delete", "x-constraints": { "group": ["tei"] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema":{ "type": "string" } }, { "name": "type", "in": "query", "required": true, "schema":{ "type": "string", "default": "person" } } ], "responses": { "410": { "description": "Entry deleted" } } }, "put": { "summary": "Save a register entry", "description": "Replace an entry with the current version from the editor", "tags": ["register"], "operationId": "rapi:save", "x-constraints": { "group": ["tei"] }, "requestBody": { "content": { "application/xml": { "schema": { "type": "string" } } } }, "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true, "example": "gnd-0000001" } ], "responses": { "201": { "description": "Entry was saved", "content": { "application/xml": { "schema": { "type": "string" } } } }, "401": { "description": "Permission denied", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/register/{id}/html": { "get": { "summary": "Retrieve HTML for a given register entry", "description": "Get the HTML fragment for a given register entry. May be used when retrieving e.g. registry content for popups asynchronously", "tags": ["register"], "operationId": "rapi:html", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "gnd-139890289" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "example": "place", "default": "person" } } ], "responses": { "200": { "description": "Returns the entire entry as HTML", "content": { "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "Register entry not found", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/sitemap.xml": { "get": { "description": "Return generated sitemap", "operationId": "sitemap:sitemap", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/xml": { "schema": { "type": "string" } } } } } } }, "/api/actions/fix-odds": { "post": { "description": "Recompile ODDs", "tags": ["actions"], "operationId": "action:fix-odds", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "security": [ { "cookieAuth": [] }, { "basicAuth": [] } ] }