{ "openapi": "3.0.0", "info": { "title": "api.zitat-service.de", "version": "1.1.4", "description": "The API provides functionality to retrieve quotes, along with related entries such as their respective authors and associated categories, from the website zitat.service.de. The content delivered by the API is available in five languages: English 🇺🇸, Español 🇪🇸, 日本語 🇯🇵, Українська 🇺🇦 and Deutsch 🇩🇪. While the content is multilingual, the API itself is provided only in English. You can find the open-source software project hosted on GitHub at github.com/muhme/quote_api.", "contact": { "name": "muhme", "email": "github@heikol.de" } }, "paths": { "/v1/author": { "get": { "x-controller-name": "AuthorsController", "x-operation-name": "getAuthor", "tags": [ "Authors" ], "responses": { "200": { "description": "OK – the author entry was retrieved successfully. Always present are the attributes `authorId` and `name`. The attributes `firstname`, `lastname`, `description` and `link` are only present if they are exist. All attributes are returned in the requested `language`.", "content": { "application/json": { "example": { "author": { "authorId": 597, "lastname": "坂本", "firstname": "龍一", "description": "日本の作曲家、ピアニスト、プロデューサー、俳優、モデル(1952年~2023年)", "link": "https://ja.wikipedia.org/wiki/坂本龍一", "name": "坂本・龍一" } } } } }, "400": { "description": "Bad Request – request format or parameters are invalid.", "content": { "application/json": { "example": { "error": { "statusCode": 400, "name": "BadRequestError", "message": "Parameter 'authorId' must be a positive integer." } } }, "text/html": { "example": " ...

BadRequestError

400 Parameter 'authorId' must be a positive integer.

..." } } }, "404": { "description": "Not Found – no author entry found for given ID.", "content": { "application/json": { "example": { "error": { "statusCode": 404, "name": "NotFoundError", "message": "No authors found for given parameters (language: 'en', page: '1', size: '100', lastname: 'XXX')" } } }, "text/html": { "example": " ...

NotFoundError

404 No authors found for given parameters (language: 'en', page: '1', size: '100', lastname: 'XXX').

..." } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "example": { "error": { "statusCode": 500, "message": "Internal Server Error" } } }, "text/html": { "example": " ...

500 Internal Server Error

... " } } }, "503": { "description": "Service Unavailable (e.g. Node.js does not run behind the Apache web server)." } }, "operationId": "get-author", "summary": "Get one author entry by ID.", "description": "Get one author entry for given `authorId` in given `language`. Always returned attributes are `authorId` and `name`. If they exist, the optional attributes `firstname`, `lastname`, `link` and `description` will be returned. All attributes are given in the requested `language`. Requested author entry have to be public.", "parameters": [ { "name": "language", "in": "query", "schema": { "type": "string", "default": "en" }, "description": "The `language` for the author entry. See `/v1/languages` for all available languages." }, { "name": "authorId", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "Authors ID. For a list of all author entries with their IDs see `/v1/authors`." } ] } }, "/v1/authors": { "get": { "x-controller-name": "AuthorsController", "x-operation-name": "getAuthors", "tags": [ "Authors" ], "responses": { "200": { "description": "OK – the list of author entries retrieved successfully. Object `paging` contains the two-letter `language` code. The `totalCount` as number of all entries, retrievable for given parameters. The requested `page` number and the requested number of entries with `size`. If the result is using preselection with `firstname`, `name` or `description` the values are shown. The `authors` result array is sorted by the the authors `lastname` first and authors `firstname` second. Attributes `authorId` and `name` are always present. The other attributes are only present if they contain values.", "content": { "application/json": { "example": { "paging": { "language": "en", "totalCount": 1, "page": 1, "size": 100, "lastname": "A", "firstname": "W" }, "authors": [ { "authorId": 140, "lastname": "Allen", "firstname": "Woody", "description": "US-American director, actor, comedian, writer and musician (born 1935)", "link": "https://en.wikipedia.org/wiki/Woody_Allen", "name": "Woody Allen" } ] } } } }, "400": { "description": "Bad Request – request format or parameters are invalid.", "content": { "application/json": { "example": { "error": { "statusCode": 400, "name": "BadRequestError", "message": "Parameter 'authorId' must be a positive integer." } } }, "text/html": { "example": " ...

BadRequestError

400 Parameter 'authorId' must be a positive integer.

..." } } }, "404": { "description": "Not Found – no entries found for the given parameters.", "content": { "application/json": { "example": { "error": { "statusCode": 404, "name": "NotFoundError", "message": "No authors found for given parameters (language: 'en', page: 1, size: 100, lastname: 'XXX')." } } }, "text/html": { "example": " ...

NotFoundError

404 No authors found for given parameters (language: 'en', page: '1', size: '100', lastname: 'XXX').

..." } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "example": { "error": { "statusCode": 500, "message": "Internal Server Error" } } }, "text/html": { "example": " ...

500 Internal Server Error

... " } } }, "503": { "description": "Service Unavailable (e.g. Node.js does not run behind the Apache web server)." } }, "operationId": "get-authors", "summary": "Get list of authors and their IDs.", "description": "Get paged list of authors. List can be restricted with `lastname`, `firstname` and `description`. These three parameters can be combined as one comma-separated parameter `lfd`. Returned `paging` contains used `language`, total number of author entries found with parameter `totalCount`, the requested page number with parameter `page`, the maximal number of page entries with parameter `size`. If the list is restricted the `paging` parameters `firstname`, `lastname` or `description` are returned. The entries of the `authors` array always contain the attributes `authorId` and `name`. If they exist, the optional attributes `firstname`, `lastname`, `link` and `description` will be returned. All attributes are given in the requested `language`. Only public authors are returned.", "parameters": [ { "name": "language", "in": "query", "schema": { "type": "string", "default": "en" }, "description": "The `language` for the author entries. See `/v1/languages` for available language codes." }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "The response is made page by page, the parameter `page` controls the page number of the result. Starting with page 1." }, { "name": "size", "in": "query", "schema": { "type": "integer", "default": 100 }, "description": "The response is made page by page, the parameter `size` controls how many entries are returned on a page." }, { "name": "lastname", "in": "query", "schema": { "type": "string" }, "description": "The beginning of the authors last name to limit the list for type-ahead. The parameter `lastname` may contain only up-to 20 characters and cannot start with an apostrophe." }, { "name": "firstname", "in": "query", "schema": { "type": "string" }, "description": "The beginning of the authors first name to limit the list for type-ahead. The parameter `lastname` may contain only up-to 20 characters and cannot start with an apostrophe." }, { "name": "description", "in": "query", "schema": { "type": "string" }, "description": "The beginning of the authors description to limit the list for type-ahead. The parameter `lastname` may contain only up-to 20 characters and cannot start with an apostrophe." }, { "name": "lfd", "in": "query", "schema": { "type": "string" }, "description": "The beginning of the authors `lastname,firstname,description` to limit the list for type-ahead. The parameter `lfd` is used to set the parameters `lastname`, `firstname` and `description`. See restrictions there." } ] } }, "/v1/categories": { "get": { "x-controller-name": "CategoriesController", "x-operation-name": "getCategories", "tags": [ "Categories" ], "responses": { "200": { "description": "OK – the category names and their IDs retrieved successfully. Object `paging` contains the two-letter `language` code, the `totalCount` as number of all entries, the requested `page` number and the requested number of entries with `size`. The `categories` result array gives the unique `id` for each entry and is sorted by `category` names.", "content": { "application/json": { "example": { "paging": { "language": "en", "totalCount": 3, "page": 1, "size": 3, "starting": "D" }, "categories": [ { "id": 569, "category": "dance" }, { "id": 74, "category": "Darkness" }, { "id": 100, "category": "Day" } ] } } } }, "400": { "description": "Bad Request – request format or parameters are invalid.", "content": { "application/json": { "example": { "error": { "statusCode": 400, "name": "BadRequestError", "message": "Parameter 'page' must be greater than or equal to 1." } } }, "text/html": { "example": " ...

BadRequestError

400 Parameter 'page' must be greater than or equal to 1.

..." } } }, "404": { "description": "Not Found – no entries found for the given parameters.", "content": { "application/json": { "example": { "error": { "statusCode": 404, "name": "NotFoundError", "message": "No categories found for given parameters: language: 'en', page: '1', size: '100', starting: 'XXX'" } } }, "text/html": { "example": " ...

NotFoundError

404 No categories found for given parameters: language: 'en', page: '1', size: '100', starting: 'XXX'

..." } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "example": { "error": { "statusCode": 500, "message": "Internal Server Error" } } }, "text/html": { "example": " ...

500 Internal Server Error

... " } } }, "503": { "description": "Service Unavailable (e.g. Node.js does not run behind the Apache web server)." } }, "operationId": "get-categories", "summary": "Get list of category names with their IDs.", "description": "Get paged list of categories. List can be restricted with parameter `starting`. Category names are in the requested `language`. Only public categories are used.", "parameters": [ { "name": "language", "in": "query", "schema": { "type": "string", "default": "en" }, "description": "The language for the category entries. See `/v1/languages` for available languages." }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "The response is made page by page, the parameter `page` controls the page number of the result. Starting with page 1." }, { "name": "size", "in": "query", "schema": { "type": "integer", "default": 100 }, "description": "The response is made page by page, the parameter `size` controls how many entries are returned on a page." }, { "name": "starting", "in": "query", "schema": { "type": "string" }, "description": "Use the `starting` parameter to specify the beginning of the category name to limit the list for preselection. The parameter `starting` may contain only up-to 20 letters or spaces." } ] } }, "/v1/languages": { "get": { "x-controller-name": "LanguagesController", "x-operation-name": "getAvailableLanguages", "tags": [ "Languages" ], "responses": { "200": { "description": "OK – available languages were successfully retrieved and returned as an array of two-letter ISO 639-1 language codes.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string", "description": "two-letter ISO 639-1 language code" } }, "example": [ "de", "en", "es", "ja", "uk" ] } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "example": { "error": { "statusCode": 500, "message": "Internal Server Error" } } }, "text/html": { "example": " ...

500 Internal Server Error

... " } } }, "503": { "description": "Service Unavailable (e.g. Node.js does not run behind the Apache web server)." } }, "operationId": "get-available-languages", "summary": "Get list of all available language codes.", "description": "Get a list of all available languages for all the content (quotes, author names, category names and links) as string-array of two-letter ISO 639-1 codes. At the moment these are de,en,es,ja,uk." } }, "/v1/quote": { "get": { "x-controller-name": "QuotationController", "x-operation-name": "getQuotationJson", "tags": [ "Random Quote" ], "responses": { "200": { "description": "OK – a random quote retrieved successfully. Always returned are the attributes `quote`, `link` and `authorId`. If they exist, the optional attributes `authorName`, `authorLink`, `source`, and `sourceLink` will be returned. If the author is unknown or not applicable, the `authorId` attribute is 0.", "content": { "application/json": { "example": { "quote": "We always overestimate the change that will occur in the next two years and underestimate the change that will occur in the next ten.", "language": "en", "link": "https://www.zitat-service.de/en/quotations/1337", "source": "The Road Ahead, Afterword, p. 316, 2006", "authorId": 286, "authorName": "Bill Gates", "authorLink": "https://en.wikipedia.org/wiki/Bill_Gates" } } } }, "400": { "description": "Bad Request – request format or parameters are invalid.", "content": { "application/json": { "example": { "error": { "statusCode": 400, "name": "BadRequestError", "message": "Parameter 'userId' must be a positive integer." } } }, "text/html": { "example": " ...

BadRequestError

400 Parameter 'userId' must be a positive integer.

..." } } }, "404": { "description": "Not Found – no random quote found for the given parameters.", "content": { "application/json": { "example": { "error": { "statusCode": 404, "name": "NotFoundError", "message": "No quote found for given parameters: language=es (Spanish), userId=42 (rezitant), categoryId=42 (Carpintero), authorId=42 (Jean Paul)!" } } }, "text/html": { "example": " ...

NotFoundError

404 No quote found for given parameters: userId=42 (rezitant), categoryId=21 (Success), authorId=42 (Jean Paul).

..." } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "example": { "error": { "statusCode": 500, "message": "Internal Server Error" } } }, "text/html": { "example": " ...

500 Internal Server Error

... " } } }, "503": { "description": "Service Unavailable (e.g. Node.js does not run behind the Apache web server)." } }, "operationId": "get-quotation", "summary": "Get one random quote with source, author and links in JSON format.", "description": "Get one random quote with source, author and links in JSON format, similar to `/v1/quote_html` for HTML format. Can be requested for `language`, `authorId`, `categoryId` or `userId`. Only public quotes are used. Multiple parameters can be combinded e.g. `language=de&authorId=46&categoryId=17` for German (de) quotes only from author Laozi (#46) and category Learning (#17).", "parameters": [ { "name": "language", "in": "query", "schema": { "type": "string" }, "description": "The language for the random quote. See `/v1/languages` for available languages. If the `language` parameter is not used, quotes are taken from all languages. Author's name and links are in the same language as the quote." }, { "name": "userId", "in": "query", "schema": { "type": "integer", "format": "int32" }, "description": "Restrict to pick-up quotes only from given `userId`. See `/v1/users` for the ID numbers of the available user entries." }, { "name": "authorId", "in": "query", "schema": { "type": "integer", "format": "int32" }, "description": "Restrict to pick-up quotes only from given `authorId`. See `/v1/authors` for the ID numbers of the available author entries." }, { "name": "categoryId", "in": "query", "schema": { "type": "integer", "format": "int32" }, "description": "Restrict to pick-up quotes only from given `categoryId`. See `/v1/categories` for the ID numbers of the available category entries." } ] } }, "/v1/quote_html": { "get": { "x-controller-name": "QuotationController", "x-operation-name": "getQuotations", "tags": [ "Random Quote" ], "responses": { "200": { "description": "OK – a random quote retrieved successfully. Always returned are a linked random quote. If they exist, the optional attributes author and source are given. Are there links for author and source existing, they entries are linked. If the author is unknown or not applicable (`authorId === 0`), this will not be displayed.", "content": { "text/html": { "example": " www.zitat-service.de
We always overestimate the change that will occur in the next two years and underestimate the change that will occur in the next ten.
The Road Ahead, Afterword, p. 316, 2006, Bill Gates
" } } }, "400": { "description": "Bad Request – request format or parameters are invalid.", "content": { "text/html": { "example": " ...

BadRequestError

400 Parameter 'userId' must be a positive integer.

..." }, "application/json": { "example": { "error": { "statusCode": 400, "name": "BadRequestError", "message": "Parameter 'userId' must be a positive integer." } } } } }, "404": { "description": "Not Found – no random quote found for the given parameters.", "content": { "text/html": { "example": " ...

NotFoundError

404 No quote found for given parameters: userId=42 (rezitant), categoryId=21 (Success), authorId=42 (Jean Paul).

..." }, "application/json": { "example": { "error": { "statusCode": 404, "name": "NotFoundError", "message": "No quote found for given parameters: language=es (Spanish), userId=42 (rezitant), categoryId=42 (Carpintero), authorId=42 (Jean Paul)!" } } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "example": { "error": { "statusCode": 500, "message": "Internal Server Error" } } }, "text/html": { "example": " ...

500 Internal Server Error

... " } } }, "503": { "description": "Service Unavailable (e.g. Node.js does not run behind the Apache web server)." } }, "operationId": "get-quotation-html", "summary": "Get a random quote with source, author and links in HTML format with optional style.", "description": "Get a random quote with source, author and links in HTML format with optional style, similar to `/v1/quote` in JSON format. All parameters are optional. Only public quotes are available. Multiple parameters can be combinded e.g. `language=de&authorId=46&categoryId=17` for German (de) quotes only from author Laozi (#46) and category Learning (#17).", "parameters": [ { "name": "language", "in": "query", "schema": { "type": "string" }, "description": "The language for the random quote. See `/v1/languages` for available languages. If the `language` parameter is not used, quotes are taken from all languages. The HTML document language, author's name, links are all in the same language as the quote." }, { "name": "userId", "in": "query", "schema": { "type": "integer", "format": "int32" }, "description": "Restrict to pick-up quotes only from given `userId`. See `/v1/users` for the ID numbers of the available user entries." }, { "name": "authorId", "in": "query", "schema": { "type": "integer", "format": "int32" }, "description": "Restrict to pick-up quotes only from given `authorId`. See `/v1/authors` for the ID numbers of the available author entries." }, { "name": "categoryId", "in": "query", "schema": { "type": "integer", "format": "int32" }, "description": "Restrict to pick-up quotes only from given `categoryId`. See `/v1/categories` for the ID numbers of the available category entries." }, { "name": "style", "in": "query", "schema": { "type": "string" }, "description": "Specifies a URL that will be used as a CSS stylesheet link in the `` section of the returned HTML document. E.g. `style=https://www.zitat-service.de/quote.css`" }, { "name": "contentOnly", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If set `true` the quote is delivered with CSS DIVs only, without the HTML header." }, { "name": "target", "in": "query", "schema": { "type": "string" }, "description": "HTML `target` attribute used in links: When not specified, all links will open in the same window/tab by browser default. Use `_blank` to open each link in a new window/tab or use a custom name like `quote_window` to open all links in a specific other window/tab. This is crucial for integrating into a webpage, for example, using an iframe. For security reasons, opening a new webpage within the original page is not allowed. The `target` parameter now allows for the links to be opened in a new tab or window." } ] } }, "/v1/users": { "get": { "x-controller-name": "UsersController", "x-operation-name": "getUsers", "tags": [ "Users" ], "responses": { "200": { "description": "OK – the login names and their IDs are retrieved successfully. The result is sorted by login names.", "content": { "application/json": { "example": { "paging": { "totalCount": 3, "page": 1, "size": 100, "starting": "ch" }, "users": [ { "id": 85, "login": "charly" }, { "id": 74, "login": "chiedelina" }, { "id": 100, "login": "chris267" } ] } } } }, "400": { "description": "Bad Request – request format or parameters are invalid.", "content": { "application/json": { "example": { "error": { "statusCode": 400, "name": "BadRequestError", "message": "Parameter 'page' must be greater than or equal to 1." } } }, "text/html": { "example": " ...

BadRequestError

400 Parameter 'page' must be greater than or equal to 1.

..." } } }, "404": { "description": "Not Found – no entries found for the given parameters.", "content": { "application/json": { "example": { "error": { "statusCode": 404, "name": "NotFoundError", "message": "No user entries found for the given parameters." } } }, "text/html": { "example": " ...

NotFoundError

404 No user entries found for given parameters.

..." } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "example": { "error": { "statusCode": 500, "message": "Internal Server Error" } } }, "text/html": { "example": " ...

500 Internal Server Error

... " } } }, "503": { "description": "Service Unavailable (e.g. Node.js does not run behind the Apache web server)." } }, "operationId": "get-users", "summary": "Get list of users login names and their IDs.", "description": "Get users login names and their IDs. Only users who have created quotes and whose quotes are public are provided.", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "The response is made page by page, the optional parameter `page` controls the page number of the result. Starting with page 1." }, { "name": "size", "in": "query", "schema": { "type": "integer", "default": 100 }, "description": "The response is made page by page, the optional parameter `size` controls how many entries are returned on a page." }, { "name": "starting", "in": "query", "schema": { "type": "string" }, "description": "The beginning of the login name to limit the list for type-ahead. The parameter `starting` may contain only up-to 20 characters and cannot start with an apostrophe." } ] } } }, "servers": [ { "url": "https://api.zitat-service.de" } ] }