Initial: new root spec for all endpoints

This commit is contained in:
Nicholas Wallace 2024-09-10 20:06:21 -07:00
parent b42fcf26fa
commit 9cc3caaaed

754
docs/newRoot.yaml Normal file
View File

@ -0,0 +1,754 @@
openapi: 3.0.0
info:
title: Audiobookshelf API
version: 0.2.0
description: Audiobookshelf API with autogenerated OpenAPI doc
license:
name: GPL-3.0
url: 'https://www.gnu.org/licenses/gpl-3.0.html'
servers:
- url: http://abs.mydomain.com:13378
description: Development server
security:
- BearerAuth: []
components:
securitySchemes:
BearerAuth:
description: Bearer authentication
type: http
scheme: bearer
schemas:
itemId:
type: string
description: A unique ID for the item. This ID is unique across all tables.
format: uuid
duration:
type: number
description: The length of the item in seconds. Will be 0 if no audio is associated with the item.
bitrate:
type: number
description: The bitrate of the audio file.
progress:
type: number
description: The user's progress through the media. Will be 1.0 if completed.
nullable: true
size:
type: integer
description: The size of the item in bytes.
title:
type: string
description: The title of the item.
titleNullable:
type: string
description: The title of the item.
nullable: true
subtitle:
type: string
description: The subtitle of the item.
nullable: true
description:
type: string
description: The description of the item.
nullable: true
isExplicit:
type: boolean
description: Whether the item contains explicit content.
isAbridged:
type: boolean
description: Whether the item is abridged.
seriesSequence:
type: object
description: The series name and sequence number of the item.
properties:
seriesId:
$ref: '#/components/schemas/itemId'
title:
$ref: '#/components/schemas/title'
sequence:
type: string
description: The sequence number of the item in the series. If the item does not have a specific sequence, this will be null.
nullable: true
seriesSequenceArray:
type: array
description: An array of series names and sequence numbers associated with the item.
nullable: true
items:
$ref: '#/components/schemas/seriesSequence'
imagePath:
type: string
description: The absolute path of the image on the server. Null if no image is associated with the item.
nullable: true
filePath:
type: string
description: The absolute path of the file on the server.
bookPerson:
type: object
description: A person associated with a book.
properties:
personId:
$ref: '#/components/schemas/itemId'
name:
type: string
description: The name of the person.
authorObjectArray:
type: array
description: An array of author objects associated with a book.
nullable: true
items:
$ref: '#/components/schemas/bookPerson'
authorNameArray:
type: array
description: An array of author names associated with a book.
nullable: true
items:
type: string
narratorObjectArray:
type: array
description: An array of narrator objects associated with a book.
nullable: true
items:
$ref: '#/components/schemas/bookPerson'
narratorNameArray:
type: array
description: An array of narrator names associated with a book.
nullable: true
items:
type: string
publisher:
type: string
description: The publisher of the book.
nullable: true
publishYear:
type: integer
description: The year the book was published.
nullable: true
isbn:
type: string
description: The ISBN of the book.
nullable: true
asin:
type: string
description: The ASIN of the book.
nullable: true
genre:
type: string
description: The genre of the item.
nullable: true
genreArray:
type: array
description: An array of genres associated with the item.
nullable: true
items:
$ref: '#/components/schemas/genre'
tag:
type: string
description: The tag of the item.
nullable: true
tagArray:
type: array
description: An array of tags associated with the item.
nullable: true
items:
$ref: '#/components/schemas/tag'
language:
type: string
description: The language of the item.
nullable: true
bookChapter:
type: object
description: A chapter in a book.
properties:
title:
type: string
description: The title of the chapter.
start:
type: number
description: The start time of the chapter in seconds.
end:
type: number
description: The end time of the chapter in seconds.
chapterArray:
type: array
description: An array of chapters in a book. Will be null if the item has no chapters.
nullable: true
items:
$ref: '#/components/schemas/bookChapter'
fileType:
type: string
description: The type of file.
enum: ['audio', 'image', 'ebook', 'metadata']
file:
type: object
description: Any media or image file associated with a book or podcast.
properties:
fileId:
$ref: '#/components/schemas/itemId'
path:
$ref: '#/components/schemas/filePath'
fileName:
type: string
description: The name of the file.
size:
$ref: '#/components/schemas/size'
duration:
$ref: '#/components/schemas/duration'
fileType:
$ref: '#/components/schemas/fileType'
audioFileCodec:
type: string
description: The codec of an audio file.
audioTrack:
type: object
description: An audio track associated with a book.
properties:
fileId:
$ref: '#/components/schemas/itemId'
path:
$ref: '#/components/schemas/filePath'
fileName:
type: string
description: The name of the file.
size:
$ref: '#/components/schemas/size'
duration:
$ref: '#/components/schemas/duration'
codec:
$ref: '#/components/schemas/audioFileCodec'
bitrate:
$ref: '#/components/schemas/bitrate'
ebookFile:
type: object
description: An ebook file associated with a book.
properties:
fileId:
$ref: '#/components/schemas/itemId'
path:
$ref: '#/components/schemas/filePath'
fileName:
type: string
description: The name of the file.
isPrimary:
type: boolean
description: Whether the file is the primary ebook file.
size:
$ref: '#/components/schemas/size'
bookObject:
type: object
description: Information about the book and its audio files.
properties:
coverPath:
$ref: '#/components/schemas/imagePath'
title:
$ref: '#/components/schemas/title'
subtitle:
$ref: '#/components/schemas/subtitle'
authors:
$ref: '#/components/schemas/authorObjectArray'
narrators:
$ref: '#/components/schemas/narratorObjectArray'
description:
$ref: '#/components/schemas/description'
genres:
$ref: '#/components/schemas/genreArray'
tags:
$ref: '#/components/schemas/tagArray'
series:
$ref: '#/components/schemas/seriesSequenceArray'
publishYear:
$ref: '#/components/schemas/publishYear'
publisher:
$ref: '#/components/schemas/publisher'
isbn:
$ref: '#/components/schemas/isbn'
asin:
$ref: '#/components/schemas/asin'
language:
$ref: '#/components/schemas/language'
explicit:
$ref: '#/components/schemas/isExplicit'
abridged:
$ref: '#/components/schemas/isAbridged'
chapters:
$ref: '#/components/schemas/chapterArray'
files:
type: array
description: All files associated with the book.
items:
$ref: '#/components/schemas/file'
audioTracks:
type: array
nullable: true
description: The audio tracks of the book. Will be null if the book is an ebook.
items:
$ref: '#/components/schemas/audioTrack'
ebookFiles:
type: array
nullable: true
description: The ebook files of the book. Will be null if no ebooks are associated with the book.
items:
$ref: '#/components/schemas/ebookFile'
progress:
$ref: '#/components/schemas/progress'
duration:
$ref: '#/components/schemas/duration'
size:
$ref: '#/components/schemas/size'
responses:
badRequest:
description: Bad request.
content:
text/html:
schema:
type: string
example: Bad request.
forbidden:
description: Forbidden.
content:
text/html:
schema:
type: string
example: Forbidden.
notFound:
description: Item not found.
content:
text/html:
schema:
type: string
example: Item not found.
tags:
- name: Book
description: Book endpoints
paths:
/api/book/{id}:
parameters:
- name: id
in: path
required: true
description: The ID of the book.
schema:
type: string
format: uuid
get:
operationId: getBookById
summary: Get book by ID
description: Get a book by its ID. This endpoint returns all of the information needed for the book details page and editing.
tags:
- Book
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/bookObject'
'404':
$ref: '#/components/responses/notFound'
post:
operationId: updateBookById
summary: Update book by ID
description: Update a book by its ID. The request body should contain only the fields that need to be updated. If a field should be cleared, the field should exist and have a value of `null`. At least one field must be present.
tags:
- Book
requestBody:
content:
application/json:
schema:
type: object
properties:
title:
$ref: '#/components/schemas/titleNullable'
subtitle:
$ref: '#/components/schemas/subtitle'
authors:
$ref: '#/components/schemas/authorNameArray'
narrators:
$ref: '#/components/schemas/narratorNameArray'
description:
$ref: '#/components/schemas/description'
genres:
$ref: '#/components/schemas/genreArray'
tags:
$ref: '#/components/schemas/tagArray'
series:
$ref: '#/components/schemas/seriesSequenceArray'
publishYear:
$ref: '#/components/schemas/publishYear'
publisher:
$ref: '#/components/schemas/publisher'
isbn:
$ref: '#/components/schemas/isbn'
asin:
$ref: '#/components/schemas/asin'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/bookObject'
'400':
$ref: '#/components/responses/badRequest'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/notFound'
delete:
operationId: deleteBookById
summary: Remove book by ID
description: Remove the book and associated entries from the database. This does not delete any files from the filesystem. If files should be deleted, use the `/api/book/{id}/hardDelete` endpoint instead.
tags:
- Book
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/bookObject'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/notFound'
/api/book/{id}/hardDelete:
parameters:
- name: id
in: path
required: true
description: The ID of the book.
schema:
type: string
format: uuid
delete:
operationId: hardDeleteBookById
summary: Hard delete book by ID
description: Hard delete the book and associated entries from the database. This deletes the book's files from the filesystem. This action cannot be undone.
tags:
- Book
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/bookObject'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/notFound'
/api/book/{id}/download:
parameters:
- name: id
in: path
required: true
description: The ID of the book.
schema:
type: string
format: uuid
get:
operationId: downloadBookById
summary: Download book by ID
description: Download the book by its ID. This endpoint will return the book's files as a zip archive.
tags:
- Book
responses:
'200':
description: OK
content:
application/zip:
schema:
type: string
format: binary
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/notFound'
/api/book/{id}/cover:
parameters:
- name: id
in: path
required: true
description: The ID of the book.
schema:
type: string
format: uuid
get:
operationId: getBookCoverById
summary: Get book cover by ID
description: Get the book cover by its ID. This endpoint will return the book's cover image. If no query parameters are provided, the image will be returned in the original format with the original dimensions.
tags:
- Book
parameters:
- name: width
in: query
required: false
description: The width of the image in pixels.
schema:
type: integer
minimum: 1
- name: height
in: query
required: false
description: The height of the image in pixels. If this parameter is not provided, the image will be scaled proportionally to the width.
schema:
type: integer
minimum: 1
- name: format
in: query
required: false
description: The format of the image. If not provided, the image will be returned in the original format.
schema:
type: string
enum: ['jpeg', 'png', 'webp']
default: 'jpeg'
responses:
'200':
description: OK
content:
image/jpeg:
schema:
type: string
format: binary
image/png:
schema:
type: string
format: binary
image/webp:
schema:
type: string
format: binary
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/notFound'
post:
operationId: uploadBookCoverById
summary: Upload book cover by ID
description: Upload the book cover image to the book by the book ID. This endpoint will replace the book's cover image with the provided image. The image should be in JPEG, PNG, or WebP format. Alternatively, the image can be provided as a URL to download the image from.
tags:
- Book
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
cover:
type: string
format: binary
application/json:
schema:
type: object
properties:
url:
type: string
description: The URL to download the image from.
format: uri
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
coverPath:
$ref: '#/components/schemas/imagePath'
success:
type: boolean
'400':
$ref: '#/components/responses/badRequest'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/notFound'
patch:
operationId: updateBookCoverById
summary: Update book cover by ID
description: Update the book cover to be an existing image in the database. This endpoint will replace the book's cover image with the provided image. The image should be in JPEG, PNG, or WebP format.
tags:
- Book
requestBody:
content:
application/json:
schema:
type: object
properties:
coverId:
$ref: '#/components/schemas/itemId'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
coverPath:
$ref: '#/components/schemas/imagePath'
success:
type: boolean
'400':
$ref: '#/components/responses/badRequest'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/notFound'
delete:
operationId: deleteBookCoverById
summary: Remove book cover by ID
description: Remove the book cover image from the book. The cover image file is not deleted but is no longer associated with the book.
tags:
- Book
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
coverPath:
$ref: '#/components/schemas/imagePath'
success:
type: boolean
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/notFound'
/api/book/{id}/match:
parameters:
- name: id
in: path
required: true
description: The ID of the book.
schema:
type: string
format: uuid
post:
operationId: matchBookById
summary: Match book by ID
description: Match the book selected by ID against an online database. This performs a quick match against the online database and returns the best match. Quick match will apply the cover from the first match and fill empty metadata fields. Metadata fields are not overwritten unless the "Prefer Matched Metadata" setting is enabled or the "force" query is set.
tags:
- Book
parameters:
- in: query
name: force
required: false
description: Whether to force the match and overwrite all metadata fields.
schema:
type: boolean
default: false
- in: query
name: provider
required: false
description: The provider to use for the match. If not provided, the default library provider will be used.
schema:
type: string
enum: ['google', 'openlibrary', 'goodreads']
- in: query
name: title
required: false
description: The title of the book to match.
schema:
type: string
- in: query
name: author
required: false
description: The author of the book to match.
schema:
type: string
- in: query
name: isbn
required: false
description: The ISBN of the book to match.
schema:
type: string
- in: query
name: asin
required: false
description: The ASIN of the book to match. Note that this needs to match the Audible page, not the Amazon page.
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/bookObject'
- type: object
properties:
updated:
type: boolean
description: Whether the book was updated with the match.
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/notFound'
/api/book/{id}/tracks:
parameters:
- name: id
in: path
required: true
description: The ID of the book.
schema:
type: string
format: uuid
patch:
operationId: updateBookTracksById
summary: Update book tracks
description: Update the book's audio tracks based on the provided file IDs. This endpoint will replace the book's audio tracks with the provided tracks. The tracks should be in the correct order.
tags:
- Book
requestBody:
content:
application/json:
schema:
type: object
properties:
trackIds:
type: array
description: The IDs of the audio files to use as tracks.
items:
$ref: '#/components/schemas/itemId'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/bookObject'
'400':
$ref: '#/components/responses/badRequest'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/notFound'
/api/book/{id}/scan:
parameters:
- name: id
in: path
required: true
description: The ID of the book.
schema:
type: string
format: uuid
post:
operationId: scanBookById
summary: Scan book by ID
description: Scan the book by its ID. This endpoint will scan the book's files and update the book's metadata based on the files found according to the metadata priority settings.
tags:
- Book
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/bookObject'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/notFound'