From afe40be957eda7d7679f69e78ff0c16f162d2af9 Mon Sep 17 00:00:00 2001 From: Nicholas Wallace Date: Sat, 30 Mar 2024 23:47:13 +0000 Subject: [PATCH] Initial large file --- docs/spec.yaml | 972 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 972 insertions(+) create mode 100644 docs/spec.yaml diff --git a/docs/spec.yaml b/docs/spec.yaml new file mode 100644 index 00000000..dfe95b69 --- /dev/null +++ b/docs/spec.yaml @@ -0,0 +1,972 @@ +openapi: 3.0.0 +info: + title: Audiobookshelf API + version: 0.1.0 + description: Audiobookshelf API with autogenerated OpenAPI doc + +servers: + - url: http://localhost:3000 + description: Development server + +components: + schemas: + mediaType: + type: string + description: The type of media, will be book or podcast. + enum: [book, podcast] + mediaMinified: + description: The minified media of the library item. + oneOf: + - $ref: '#/components/schemas/bookMinified' + bookCoverPath: + description: The absolute path on the server of the cover file. Will be null if there is no cover. + type: string + nullable: true + example: /audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg + bookBase: + type: object + description: Base book schema + properties: + libraryItemId: + $ref: '#/components/schemas/libraryItemId' + coverPath: + $ref: '#/components/schemas/bookCoverPath' + tags: + $ref: '#/components/schemas/tags' + audioFiles: + type: array + items: + $ref: '#/components/schemas/audioFile' + chapters: + type: array + items: + $ref: '#/components/schemas/bookChapter' + missingParts: + description: Any parts missing from the book by track index. + type: array + items: + type: integer + ebookFile: + $ref: '#/components/schemas/ebookFile' + bookMinified: + type: object + description: Minified book schema. Does not depend on `bookBase` because there's pretty much no overlap. + properties: + metadata: + $ref: '#/components/schemas/bookMetadataMinified' + coverPath: + $ref: '#/components/schemas/bookCoverPath' + tags: + $ref: '#/components/schemas/tags' + numTracks: + description: The number of tracks the book's audio files have. + type: integer + example: 1 + numAudioFiles: + description: The number of audio files the book has. + type: integer + example: 1 + numChapters: + description: The number of chapters the book has. + type: integer + example: 1 + numMissingParts: + description: The total number of missing parts the book has. + type: integer + example: 0 + numInvalidAudioFiles: + description: The number of invalid audio files the book has. + type: integer + example: 0 + duration: + $ref: '#/components/schemas/durationSec' + size: + $ref: '#/components/schemas/size' + ebookFormat: + description: The format of ebook of the book. Will be null if the book is an audiobook. + type: string + nullable: true + narrators: + description: The narrators of the audiobook. + type: array + items: + type: string + example: Sam Tsoutsouvas + bookMetadataBase: + type: object + description: The base book metadata object for minified, normal, and extended schemas to inherit from. + properties: + title: + description: The title of the book. Will be null if unknown. + type: string + nullable: true + example: Wizards First Rule + subtitle: + description: The subtitle of the book. Will be null if there is no subtitle. + type: string + nullable: true + genres: + description: The genres of the book. + type: array + items: + type: string + example: ["Fantasy", "Sci-Fi", "Nonfiction: History"] + publishedYear: + description: The year the book was published. Will be null if unknown. + type: string + nullable: true + example: '2008' + publishedDate: + description: The date the book was published. Will be null if unknown. + type: string + nullable: true + publisher: + description: The publisher of the book. Will be null if unknown. + type: string + nullable: true + example: Brilliance Audio + description: + description: A description for the book. Will be null if empty. + type: string + nullable: true + example: >- + The masterpiece that started Terry Goodkind's New York Times bestselling + epic Sword of Truth In the aftermath of the brutal murder of his father, + a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest + sanctuary seeking help...and more. His world, his very beliefs, are + shattered when ancient debts come due with thundering violence. In a + dark age it takes courage to live, and more than mere courage to + challenge those who hold dominion, Richard and Kahlan must take up that + challenge or become the next victims. Beyond awaits a bewitching land + where even the best of their hearts could betray them. Yet, Richard + fears nothing so much as what secrets his sword might reveal about his + own soul. Falling in love would destroy them - for reasons Richard can't + imagine and Kahlan dare not say. In their darkest hour, hunted + relentlessly, tormented by treachery and loss, Kahlan calls upon Richard + to reach beyond his sword - to invoke within himself something more + noble. Neither knows that the rules of battle have just changed...or + that their time has run out. Wizard's First Rule is the beginning. One + book. One Rule. Witness the birth of a legend. + isbn: + description: The ISBN of the book. Will be null if unknown. + type: string + nullable: true + asin: + description: The ASIN of the book. Will be null if unknown. + type: string + nullable: true + example: B002V0QK4C + language: + description: The language of the book. Will be null if unknown. + type: string + nullable: true + explicit: + description: Whether the book has been marked as explicit. + type: boolean + example: false + bookMetadataMinified: + type: object + description: The minified metadata for a book in the database. + allOf: + - $ref : '#/components/schemas/bookMetadataBase' + - type: object + properties: + titleIgnorePrefix: + description: The title of the book with any prefix moved to the end. + type: string + authorName: + description: The name of the book's author(s). + type: string + example: Terry Goodkind + authorNameLF: + description: The name of the book's author(s) with last names first. + type: string + example: Goodkind, Terry + narratorName: + description: The name of the audiobook's narrator(s). + type: string + example: Sam Tsoutsouvas + seriesName: + description: The name of the book's series. + type: string + example: Sword of Truth + bookChapter: + type: object + description: A book chapter. Includes the title and timestamps. + properties: + id: + description: The ID of the book chapter. + type: integer + example: 0 + start: + description: When in the book (in seconds) the chapter starts. + type: integer + example: 0 + end: + description: When in the book (in seconds) the chapter ends. + type: number + example: 6004.6675 + title: + description: The title of the chapter. + type: string + example: Wizards First Rule 01 Chapter 1 + audioFile: + type: object + description: An audio file for a book. Includes audio metadata and track numbers. + properties: + index: + description: The index of the audio file. + type: integer + example: 1 + ino: + $ref: '#/components/schemas/inode' + metadata: + $ref: '#/components/schemas/fileMetadata' + addedAt: + $ref: '#/components/schemas/addedAt' + updatedAt: + $ref: '#/components/schemas/updatedAt' + trackNumFromMeta: + description: The track number of the audio file as pulled from the file's metadata. Will be null if unknown. + type: integer + nullable: true + example: 1 + discNumFromMeta: + description: The disc number of the audio file as pulled from the file's metadata. Will be null if unknown. + type: string + nullable: true + trackNumFromFilename: + description: The track number of the audio file as determined from the file's name. Will be null if unknown. + type: integer + nullable: true + example: 1 + discNumFromFilename: + description: The disc number of the audio file as determined from the file's name. Will be null if unknown. + type: string + nullable: true + manuallyVerified: + description: Whether the audio file has been manually verified by a user. + type: boolean + invalid: + description: Whether the audio file is missing from the server. + type: boolean + exclude: + description: Whether the audio file has been marked for exclusion. + type: boolean + error: + description: Any error with the audio file. Will be null if there is none. + type: string + nullable: true + format: + description: The format of the audio file. + type: string + example: MP2/3 (MPEG audio layer 2/3) + duration: + $ref: '#/components/schemas/durationSec' + bitRate: + description: The bit rate (in bit/s) of the audio file. + type: integer + example: 64000 + language: + description: The language of the audio file. + type: string + nullable: true + codec: + description: The codec of the audio file. + type: string + example: mp3 + timeBase: + description: The time base of the audio file. + type: string + example: 1/14112000 + channels: + description: The number of channels the audio file has. + type: integer + example: 2 + channelLayout: + description: The layout of the audio file's channels. + type: string + example: stereo + chapters: + description: If the audio file is part of an audiobook, the chapters the file contains. + type: array + items: + $ref: '#/components/schemas/bookChapter' + embeddedCoverArt: + description: The type of embedded cover art in the audio file. Will be null if none exists. + type: string + nullable: true + metaTags: + $ref: '#/components/schemas/audioMetaTags' + mimeType: + description: The MIME type of the audio file. + type: string + example: audio/mpeg + ebookFile: + type: object + description: An ebook file for a library item. + nullable: true + properties: + ino: + $ref: '#/components/schemas/inode' + metadata: + $ref: '#/components/schemas/fileMetadata' + ebookFormat: + description: The ebook format of the ebook file. + type: string + example: epub + addedAt: + $ref: '#/components/schemas/addedAt' + updatedAt: + $ref: '#/components/schemas/updatedAt' + fileMetadata: + type: object + description: The metadata for a file, including the path, size, and unix timestamps of the file. + nullable: true + properties: + filename: + description: The filename of the file. + type: string + example: Wizards First Rule 01.mp3 + ext: + description: The file extension of the file. + type: string + example: .mp3 + path: + description: The absolute path on the server of the file. + type: string + example: >- + /audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry + Goodkind - SOT Bk01 - Wizards First Rule 01.mp3 + relPath: + description: The path of the file, relative to the book's or podcast's folder. + type: string + example: Wizards First Rule 01.mp3 + size: + $ref: '#/components/schemas/size' + mtimeMs: + description: The time (in ms since POSIX epoch) when the file was last modified on disk. + type: integer + example: 1632223180278 + ctimeMs: + description: The time (in ms since POSIX epoch) when the file status was changed on disk. + type: integer + example: 1645978261001 + birthtimeMs: + description: The time (in ms since POSIX epoch) when the file was created on disk. Will be 0 if unknown. + type: integer + example: 0 + audioMetaTags: + description: ID3 metadata tags pulled from the audio file on import. Only non-null tags will be returned in requests. + type: object + properties: + tagAlbum: + type: string + nullable: true + example: SOT Bk01 + tagArtist: + type: string + nullable: true + example: Terry Goodkind + tagGenre: + type: string + nullable: true + example: Audiobook Fantasy + tagTitle: + type: string + nullable: true + example: Wizards First Rule 01 + tagSeries: + type: string + nullable: true + tagSeriesPart: + type: string + nullable: true + tagTrack: + type: string + nullable: true + example: 01/20 + tagDisc: + type: string + nullable: true + tagSubtitle: + type: string + nullable: true + tagAlbumArtist: + type: string + nullable: true + example: Terry Goodkind + tagDate: + type: string + nullable: true + tagComposer: + type: string + nullable: true + example: Terry Goodkind + tagPublisher: + type: string + nullable: true + tagComment: + type: string + nullable: true + tagDescription: + type: string + nullable: true + tagEncoder: + type: string + nullable: true + tagEncodedBy: + type: string + nullable: true + tagIsbn: + type: string + nullable: true + tagLanguage: + type: string + nullable: true + tagASIN: + type: string + nullable: true + tagOverdriveMediaMarker: + type: string + nullable: true + tagOriginalYear: + type: string + nullable: true + tagReleaseCountry: + type: string + nullable: true + tagReleaseType: + type: string + nullable: true + tagReleaseStatus: + type: string + nullable: true + tagISRC: + type: string + nullable: true + tagMusicBrainzTrackId: + type: string + nullable: true + tagMusicBrainzAlbumId: + type: string + nullable: true + tagMusicBrainzAlbumArtistId: + type: string + nullable: true + tagMusicBrainzArtistId: + type: string + nullable: true + addedAt: + type: integer + description: The time (in ms since POSIX epoch) when added to the server. + example: 1633522963509 + createdAt: + type: integer + description: The time (in ms since POSIX epoch) when was created. + example: 1633522963509 + updatedAt: + type: integer + description: The time (in ms since POSIX epoch) when last updated. + example: 1633522963509 + size: + description: The total size (in bytes) of the item or file. + type: integer + example: 268824228 + durationSec: + description: The total length (in seconds) of the item or file. + type: number + example: 33854.905 + tags: + description: Tags applied to items. + type: array + items: + type: string + example: ["To Be Read", "Genre: Nonfiction"] + inode: + description: The inode of the item in the file system. + type: string + format: "[0-9]*" + example: '649644248522215260' + seriesId: + type: string + description: The ID of the series. + format: uuid + example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b + seriesName: + description: The name of the series. + type: string + example: Sword of Truth + folderId: + type: string + description: The ID of the folder. + format: uuid + example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b + folder: + type: object + description: Folder used in library + properties: + id: + $ref: '#/components/schemas/folderId' + fullPath: + description: The path on the server for the folder. (Read Only) + type: string + example: /podcasts + libraryId: + $ref: '#/components/schemas/libraryId' + addedAt: + $ref: '#/components/schemas/addedAt' + authorUpdated: + description: Whether the author was updated without errors. Will not exist if author was merged. + type: boolean + nullable: true + authorId: + type: string + description: The ID of the author. + format: uuid + example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b + authorASIN: + type: string + description: The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier. + nullable: true + example: B000APZOQA + authorName: + description: The name of the author. + type: string + example: Terry Goodkind + authorSeries: + type: object + description: Series and the included library items that an author has written. + properties: + id: + $ref: '#/components/schemas/seriesId' + name: + $ref: '#/components/schemas/seriesName' + items: + description: The items in the series. Each library item's media's metadata will have a `series` attribute, a `Series Sequence`, which is the matching series. + type: array + items: + $ref: '#/components/schemas/libraryItemMinified' + author: + description: An author object which includes a description and image path. + type: object + properties: + id: + $ref: '#/components/schemas/authorId' + asin: + $ref: '#/components/schemas/authorASIN' + name: + $ref: '#/components/schemas/authorName' + description: + description: A description of the author. Will be null if there is none. + type: string + nullable: true + example: | + Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork, + ‘The Sword of Truth’. He has written 30+ major, bestselling novels, has been published in more than 20 + languages world-wide, and has sold more than 26 Million books. ‘The Sword of Truth’ is a revered literary + tour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing. Terry Goodkind's + brilliant books are character-driven stories, with a focus on the complexity of the human psyche. Goodkind + has an uncanny grasp for crafting compelling stories about people like you and me, trapped in terrifying + situations. + imagePath: + description: The absolute path for the author image located in the `metadata/` directory. Will be null if there is no image. + type: string + nullable: true + example: /metadata/authors/aut_bxxbyjiptmgb56yzoz.jpg + addedAt: + $ref: '#/components/schemas/addedAt' + updatedAt: + $ref: '#/components/schemas/updatedAt' + authorWithItems: + type: object + description: The author schema with an array of items they are associated with. + allOf: + - $ref: '#/components/schemas/author' + - type: object + properties: + libraryItems: + description: The items associated with the author + type: array + items: + $ref: '#/components/schemas/libraryItemMinified' + authorWithSeries: + type: object + description: The author schema with an array of items and series they are associated with. + allOf: + - $ref: '#/components/schemas/authorWithItems' + - type: object + properties: + series: + description: The series associated with the author + type: array + items: + $ref: '#/components/schemas/authorSeries' + authorMinified: + type: object + description: Minified author object which only contains the author name and ID. + properties: + id: + $ref: '#/components/schemas/authorId' + name: + $ref: '#/components/schemas/authorName' + authorExpanded: + type: object + description: The author schema with the total number of books in the library. + allOf: + - $ref: '#/components/schemas/author' + - type: object + properties: + numBooks: + description: The number of books associated with the author in the library. + type: integer + example: 1 + oldLibraryId: + type: string + description: The ID of the libraries created on server version 2.2.23 and before. + format: "lib_[a-z0-9]{18}" + example: lib_o78uaoeuh78h6aoeif + libraryId: + type: string + description: The ID of the library. + format: uuid + example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b + oldLibraryItemId: + description: The ID of library items on server version 2.2.23 and before. + type: string + nullable: true + format: "li_[a-z0-9]{18}" + example: li_o78uaoeuh78h6aoeif + libraryItemId: + type: string + description: The ID of library items after 2.3.0. + format: uuid + example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b + libraryItemBase: + type: object + description: Base library item schema + properties: + id: + $ref: '#/components/schemas/libraryItemId' + oldLibraryItemId: + $ref: '#/components/schemas/oldLibraryItemId' + ino: + $ref: '#/components/schemas/inode' + libraryId: + $ref: '#/components/schemas/libraryId' + folderId: + $ref: '#/components/schemas/folderId' + path: + description: The path of the library item on the server. + type: string + relPath: + description: The path, relative to the library folder, of the library item. + type: string + isFile: + description: Whether the library item is a single file in the root of the library folder. + type: boolean + mtimeMs: + description: The time (in ms since POSIX epoch) when the library item was last modified on disk. + type: integer + ctimeMs: + description: The time (in ms since POSIX epoch) when the library item status was changed on disk. + type: integer + birthtimeMs: + description: The time (in ms since POSIX epoch) when the library item was created on disk. Will be 0 if unknown. + type: integer + addedAt: + $ref: '#/components/schemas/addedAt' + updatedAt: + $ref: '#/components/schemas/updatedAt' + isMissing: + description: Whether the library item was scanned and no longer exists. + type: boolean + isInvalid: + description: Whether the library item was scanned and no longer has media files. + type: boolean + mediaType: + $ref: '#/components/schemas/mediaType' + libraryItemMinified: + type: object + description: A single item on the server, like a book or podcast. Minified media format. + allOf: + - $ref : '#/components/schemas/libraryItemBase' + - type: object + properties: + media: + $ref: '#/components/schemas/mediaMinified' + parameters: + authorID: + name: id + in: path + description: Author ID + required: true + schema: + $ref: '#/components/schemas/authorId' + authorInclude: + name: include + in: query + description: A comma separated list of what to include with the author. The options are `items` and `series`. `series` will only have an effect if `items` is included. + required: false + schema: + type: string + example: "items" + examples: + empty: + summary: Do not return library items + value: "" + itemOnly: + summary: Only return library items + value: "items" + itemsAndSeries: + summary: Return library items and series + value: "items,series" + authorLibraryId: + name: library + in: query + description: The ID of the library to to include filter included items from. + required: false + schema: + $ref: '#/components/schemas/libraryId' + asin: + name: asin + in: query + description: The Audible Identifier (ASIN). + required: false + schema: + $ref: '#/components/schemas/authorASIN' + authorSearchName: + name: q + in: query + description: The name of the author to use for searching. + required: false + schema: + type: string + example: Terry Goodkind + authorName: + name: name + in: query + description: The new name of the author. + required: false + schema: + $ref: '#/components/schemas/authorName' + authorDescription: + name: description + in: query + description: The new description of the author. + required: false + schema: + type: string + nullable: true + example: Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork, ‘The Sword of Truth’. He has written 30+ major, bestselling novels, has been published in more than 20 languages world-wide, and has sold more than 26 Million books. ‘The Sword of Truth’ is a revered literary tour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing. + authorImagePath: + name: imagePath + in: query + description: The new absolute path for the author image. + required: false + schema: + type: string + nullable: true + example: /metadata/authors/aut_z3leimgybl7uf3y4ab.jpg + imageURL: + name: url + in: query + description: The URL of the image to add to the server + required: true + schema: + type: string + format: uri + example: https://images-na.ssl-images-amazon.com/images/I/51NoQTm33OL.__01_SX120_CR0,0,120,120__.jpg + imageWidth: + name: width + in: query + description: The requested width of image in pixels. + schema: + type: integer + default: 400 + example: 400 + example: 400 + imageHeight: + name: height + in: query + description: The requested height of image in pixels. If `null`, the height is scaled to maintain aspect ratio based on the requested width. + schema: + type: integer + nullable: true + default: null + example: 600 + examples: + scaleHeight: + summary: Scale height with width + value: null + fixedHeight: + summary: Force height of image + value: 600 + imageFormat: + name: format + in: query + description: The requested output format. + schema: + type: string + default: jpeg + example: webp + imageRaw: + name: raw + in: query + description: Return the raw image without scaling if true. + schema: + type: boolean + default: false + responses: + ok200: + description: OK + author404: + description: Author not found. + content: + text/html: + schema: + type: string + example: Not found + paths: + /api/authors/{id}: + get: + operationId: getAuthorByID + summary: Get a single author by ID on server + tags: + - Authors + parameters: + - $ref: '#/components/parameters/authorID' + - $ref: '#/components/parameters/authorInclude' + - $ref: '#/components/parameters/authorLibraryId' + responses: + 200: + description: getAuthorByID OK + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/author' + - $ref: '#/components/schemas/authorWithItems' + - $ref: '#/components/schemas/authorWithSeries' + 404: + $ref: '#/components/responses/author404' + /api/authors/{id}: + patch: + operationId: updateAuthorByID + summary: Update a single author by ID on server. This endpoint will merge two authors if the new author name matches another author in the database. + tags: + - Authors + parameters: + - $ref: '#/components/parameters/authorID' + - $ref: '#/components/parameters/asin' + - $ref: '#/components/parameters/authorName' + - $ref: '#/components/parameters/authorDescription' + - $ref: '#/components/parameters/authorImagePath' + responses: + 200: + description: updateAuthorByID OK + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/author' + - $ref: '#/components/schemas/authorUpdated' + - type: object + properties: + merged: + description: Will only exist and be `true` if the author was merged with another author + type: boolean + nullable: true + 404: + $ref: '#/components/responses/author404' + /api/authors/{id}: + delete: + operationId: deleteAuthorByID + summary: Delete a single author by ID on server and remove author from all books. + tags: + - Authors + parameters: + - $ref: '#/components/parameters/authorID' + responses: + 200: + $ref: '#/components/responses/ok200' + 404: + $ref: '#/components/responses/author404' + /api/authors/{id}/image: + post: + operationId: setAuthorImageByID + summary: Set an author image using a provided URL. + tags: + - Authors + parameters: + - $ref: '#/components/parameters/authorID' + - $ref: '#/components/parameters/imageURL' + responses: + 200: + description: setAuthorImageByID OK + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/author' + 404: + $ref: '#/components/responses/author404' + /api/authors/{id}/image: + delete: + operationId: deleteAuthorImageByID + summary: Delete an author image from the server and remove the image from the database. + tags: + - Authors + parameters: + - $ref: '#/components/parameters/authorID' + responses: + 200: + $ref: '#/components/responses/ok200' + 404: + $ref: '#/components/responses/author404' + /api/authors/{id}/match: + post: + operationId: matchAuthorByID + summary: Match the author against Audible using quick match. Quick match updates the author's description and image (if no image already existed) with information from audible. Either `asin` or `q` must be provided, with `asin` taking priority if both are provided. + tags: + - Authors + parameters: + - $ref: '#/components/parameters/authorID' + - $ref: '#/components/parameters/asin' + - $ref: '#/components/parameters/authorSearchName' + responses: + 200: + description: matchAuthorByID OK + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/author' + - $ref: '#/components/schemas/authorUpdated' + 404: + $ref: '#/components/responses/author404' + /api/authors/{id}/image: + patch: + operationId: getAuthorImageByID + summary: Return the author image by author ID. + tags: + - Authors + parameters: + - $ref: '#/components/parameters/authorID' + - $ref: '#/components/parameters/imageWidth' + - $ref: '#/components/parameters/imageHeight' + - $ref: '#/components/parameters/imageFormat' + - $ref: '#/components/parameters/imageRaw' + responses: + 200: + description: getAuthorImageByID OK + content: + image/*: + schema: + type: string + format: binary + 404: + $ref: '#/components/responses/author404' +tags: + - name: Authors + description: Author endpoints