groove/audiobookshelf
1
0
Fork 0
mirror of https://github.com/advplyr/audiobookshelf.git synced 2026-07-11 03:41:42 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

Schema updates from August 3 (#1)

Browse source 
* Update: formatting

* Fix: libraryItemController `play` endpoint
+ Endpoints cannot have optional path parameters
+ Moved schemas to `components` section

* Fix: MeController optional path parameters

* Fix: Books do not have `episodeId` in `mediaProgress`

* Fix: `PlaybackSession` oneOf between book and podcast

* Update: bundled spec

* Fix: `allowReserved` in LibraryItem include query

* Add: tags to AuthController endpoints

* Fix: summary of play endpoints

* Update: bundled spec
This commit is contained in:
Nicholas W 2024-08-04 00:00:32 -07:00 • committed by GitHub
parent 7274b87aca
commit 3a91092fbf
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
13 changed files with 561 additions and 441 deletions
Download patch file Download diff file Expand all files Collapse all files

7
docs/controllers/AuthController.yaml
View file

@ -4,6 +4,8 @@ paths:
summary: Login to the server
description: Logs in a client to the server, returning information about the user and server.
operationId: login
tags:
- Auth
requestBody:
required: true
content:
@ -15,9 +17,6 @@ paths:
$ref: '../objects/entities/User.yaml#/components/schemas/username'
password:
$ref: '../objects/entities/User.yaml#/components/schemas/password'
required:
- username
- password
responses:
'200':
description: Success
@ -40,6 +39,8 @@ paths:
summary: Logout from the server
description: Logs out a client from the server. If the socketId parameter is provided, the server removes the socket from the client list.
operationId: logout
tags:
- Auth
requestBody:
required: true
content:

192
docs/controllers/LibraryItemController.yaml
View file

@ -1,3 +1,69 @@
components:
schemas:
parameters:
include:
in: query
name: include
description: A comma separated list of what to include with the library item. The options are progress, rssfeed, authors (for books), and downloads (for podcasts). expanded must be 1 for include to have an effect.
allowReserved: true
schema:
type: string
expanded:
in: query
name: expanded
description: Whether to return Library Item Expanded instead. 0 for false, 1 for true.
schema:
type: integer
example: 1
episode:
in: query
name: episode
description: If requesting progress for a podcast, the episode ID to get progress for.
schema:
$ref: '../objects/mediaTypes/Podcast.yaml#/components/schemas/podcastId'
deviceInfo:
in: query
name: deviceInfo
description: The device information to send to the server.
schema:
$ref: '../objects/entities/Device.yaml#/components/schemas/deviceInfo'
forceDirectPlay:
in: query
name: forceDirectPlay
description: Whether to force direct play of the library item.
schema:
type: boolean
example: false
forceTranscode:
in: query
name: forceTranscode
description: Whether to force transcoding of the library item.
schema:
type: boolean
example: false
supportedMimeTypes:
in: query
name: supportedMimeTypes
description: The supported mime types for the device.
schema:
type: array
items:
type: string
mediaPlayer:
in: query
name: mediaPlayer
description: The media player to use.
schema:
type: string
responses:
libraryItem404:
description: Not Found
content:
text/html:
schema:
type: string
description: The library item does not exist.
example: Not Found
paths:
/api/items/{id}:
parameters:
@ -14,32 +80,50 @@ paths:
tags:
- LibraryItem
parameters:
- in: query
name: include
description: A comma separated list of what to include with the library item. The options are progress, rssfeed, authors (for books), and downloads (for podcasts). expanded must be 1 for include to have an effect.
schema:
type: string
- in: query
name: expanded
description: Whether to return Library Item Expanded instead. 0 for false, 1 for true.
schema:
type: integer
example: 1
- in: query
name: episode
description: If requesting progress for a podcast, the episode ID to get progress for.
schema:
$ref: '../objects/mediaTypes/Podcast.yaml#/components/schemas/podcastId'
- $ref: '#/components/schemas/parameters/include'
- $ref: '#/components/schemas/parameters/expanded'
- $ref: '#/components/schemas/parameters/episode'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
description: TODO
oneOf:
- $ref: '../objects/LibraryItem.yaml#/components/schemas/libraryItem'
description: OK
content:
application/json:
schema:
type: object
description: TODO
oneOf:
- $ref: '../objects/LibraryItem.yaml#/components/schemas/libraryItem'
'404':
$ref: '#/components/responses/libraryItem404'
/api/items/{id}/play:
parameters:
- name: id
in: path
description: The ID of the library item.
required: true
schema:
$ref: '../objects/LibraryItem.yaml#/components/schemas/libraryItemId'
post:
operationId: playLibraryItem
summary: Play a library item
description: Play a library item by ID.
tags:
- LibraryItem
parameters:
- $ref: '#/components/schemas/parameters/deviceInfo'
- $ref: '#/components/schemas/parameters/forceDirectPlay'
- $ref: '#/components/schemas/parameters/forceTranscode'
- $ref: '#/components/schemas/parameters/supportedMimeTypes'
- $ref: '#/components/schemas/parameters/mediaPlayer'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSessionExpanded'
'404':
$ref: '#/components/responses/libraryItem404'
/api/items/{id}/play/{episodeId}:
parameters:
- name: id
@ -51,57 +135,27 @@ paths:
- name: episodeId
in: path
description: The ID of the episode to play.
required: false
required: true
schema:
$ref: '../objects/mediaTypes/Podcast.yaml#/components/schemas/podcastId'
post:
operationId: playLibraryItem
summary: Play a library item.
description: Play a library item.
operationId: playLibraryItemPodcastEpisode
summary: Play a podcast episode
description: Play a podcast by library item ID and episode ID.
tags:
- LibraryItem
parameters:
- in: query
name: deviceInfo
description: The device information to send to the server.
schema:
$ref: '../objects/entities/Device.yaml#/components/schemas/deviceInfo'
- in: query
name: forceDirectPlay
description: Whether to force direct play of the library item.
schema:
type: boolean
example: false
- in: query
name: forceTranscode
description: Whether to force transcoding of the library item.
schema:
type: boolean
example: false
- in: query
name: supportedMimeTypes
description: The supported mime types for the device.
schema:
type: array
items:
type: string
- in: query
name: mediaPlayer
description: The media player to use.
schema:
type: string
- $ref: '#/components/schemas/parameters/deviceInfo'
- $ref: '#/components/schemas/parameters/forceDirectPlay'
- $ref: '#/components/schemas/parameters/forceTranscode'
- $ref: '#/components/schemas/parameters/supportedMimeTypes'
- $ref: '#/components/schemas/parameters/mediaPlayer'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSessionExpanded'
description: OK
content:
application/json:
schema:
$ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSessionExpanded'
'404':
description: Not Found
content:
text/html:
schema:
type: string
description: The library item does not have any audio tracks to play.
example: Not Found
$ref: '#/components/responses/libraryItem404'

250
docs/controllers/MeController.yaml
View file

@ -4,6 +4,14 @@ components:
description: The total time listened in seconds.
type: integer
example: 123456
responses:
me404:
description: Not Found
content:
html/text:
schema:
type: string
example: Not Found
paths:
/api/me:
get:
@ -14,11 +22,34 @@ paths:
- Me
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '../objects/entities/User.yaml#/components/schemas/user'
description: Success
content:
application/json:
schema:
$ref: '../objects/entities/User.yaml#/components/schemas/user'
/api/me/progress/{libraryItemId}:
parameters:
- name: libraryItemId
in: path
description: The ID of the library item.
required: true
schema:
$ref: '../objects/LibraryItem.yaml#/components/schemas/libraryItemId'
get:
operationId: getProgressLibraryItem
summary: Get the user's progress for a library item.
description: Get the user's progress for a library item.
tags:
- Me
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '../objects/Media.yaml#/components/schemas/mediaProgress'
'404':
$ref: '#/components/responses/me404'
/api/me/progress/{libraryItemId}/{episodeId}:
parameters:
- name: libraryItemId
@ -30,57 +61,24 @@ paths:
- name: episodeId
in: path
description: The ID of the episode to get progress for.
required: false
required: true
schema:
$ref: '../objects/mediaTypes/Podcast.yaml#/components/schemas/podcastId'
get:
operationId: getProgress
summary: Get the user's progress for a library item.
description: Get the user's progress for a library item.
operationId: getProgressPodcastEpisode
summary: Get the user's progress for a podcast episode.
description: Get the user's progress for a podcast episode.
tags:
- Me
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '../objects/Media.yaml#/components/schemas/mediaProgress'
description: OK
content:
application/json:
schema:
$ref: '../objects/Media.yaml#/components/schemas/mediaProgressPodcastEpisode'
'404':
description: Not Found
content:
html/text:
schema:
type: string
example: Not Found
/api/me/progress/{mediaId}:
parameters:
- name: mediaId
in: path
description: The ID of the media progress.
required: true
schema:
$ref: '../objects/Media.yaml#/components/schemas/mediaProgressId'
get:
operationId: getProgressById
summary: Get the user's progress for a media item.
description: Get the user's progress for a media item.
tags:
- Me
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '../objects/Media.yaml#/components/schemas/mediaProgress'
'404':
description: Not Found
content:
html/text:
schema:
type: string
example: Not Found
$ref: '#/components/responses/me404'
/api/me/listening-sessions:
get:
operationId: getListeningSessions
@ -94,32 +92,32 @@ paths:
description: The number of items per page.
required: true
schema:
$ref: '../schemas.yaml#/components/schemas/limit'
$ref: '../schemas.yaml#/components/schemas/limit'
- name: page
in: query
description: The page number (zero indexed) to return.
required: true
schema:
$ref: '../schemas.yaml#/components/schemas/page'
$ref: '../schemas.yaml#/components/schemas/page'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
total:
$ref: '../schemas.yaml#/components/schemas/total'
numPages:
description: The number of pages.
type: integer
itemsPerPage:
$ref: '../schemas.yaml#/components/schemas/limit'
sessions:
type: array
items:
$ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSession'
description: OK
content:
application/json:
schema:
type: object
properties:
total:
$ref: '../schemas.yaml#/components/schemas/total'
numPages:
description: The number of pages.
type: integer
itemsPerPage:
$ref: '../schemas.yaml#/components/schemas/limit'
sessions:
type: array
items:
$ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSession'
/api/me/items-in-progress:
get:
operationId: getItemsInProgress
@ -133,26 +131,26 @@ paths:
description: The number of items to return.
required: false
schema:
$ref: '../schemas.yaml#/components/schemas/limit'
$ref: '../schemas.yaml#/components/schemas/limit'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
total:
$ref: '../schemas.yaml#/components/schemas/total'
numPages:
description: The number of pages.
type: integer
itemsPerPage:
$ref: '../schemas.yaml#/components/schemas/limit'
items:
type: array
items:
$ref: '../objects/LibraryItem.yaml#/components/schemas/libraryItemMinified'
description: OK
content:
application/json:
schema:
type: object
properties:
total:
$ref: '../schemas.yaml#/components/schemas/total'
numPages:
description: The number of pages.
type: integer
itemsPerPage:
$ref: '../schemas.yaml#/components/schemas/limit'
items:
type: array
items:
$ref: '../objects/LibraryItem.yaml#/components/schemas/libraryItemMinified'
/api/me/listening-stats:
get:
operationId: getListeningStats
@ -162,46 +160,46 @@ paths:
- Me
responses:
'200':
description: OK
content:
application/json:
schema:
description: OK
content:
application/json:
schema:
type: object
properties:
totalTime:
$ref: '#/components/schemas/totalTime'
items:
type: object
description: A list of library items the user has listened to, keyed by their item IDs.
additionalProperties:
type: object
properties:
totalTime:
$ref: '#/components/schemas/totalTime'
items:
type: object
description: A list of library items the user has listened to, keyed by their item IDs.
additionalProperties:
type: object
properties:
id:
type: string
description: The ID of the library item.
timeListening:
type: integer
description: The time (in seconds) the user listened to this library item.
mediaMetadata:
oneOf:
- $ref: '../objects/metadata/BookMetadata.yaml#/components/schemas/bookMetadata'
- $ref: '../objects/metadata/PodcastMetadata.yaml#/components/schemas/PodcastMetadata'
days:
type: object
description: A mapping of days to total listening times.
additionalProperties:
type: integer
description: The total time (in seconds) listened to on that day.
dayOfWeek:
type: object
description: A mapping of days of the week to total listening times.
additionalProperties:
type: integer
description: The total time (in seconds) listened to on that day of the week.
today:
type: integer
description: The time (in seconds) the user has listened to library items today.
recentSessions:
type: array
items:
$ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSession'
id:
type: string
description: The ID of the library item.
timeListening:
type: integer
description: The time (in seconds) the user listened to this library item.
mediaMetadata:
oneOf:
- $ref: '../objects/metadata/BookMetadata.yaml#/components/schemas/bookMetadata'
- $ref: '../objects/metadata/PodcastMetadata.yaml#/components/schemas/PodcastMetadata'
days:
type: object
description: A mapping of days to total listening times.
additionalProperties:
type: integer
description: The total time (in seconds) listened to on that day.
dayOfWeek:
type: object
description: A mapping of days of the week to total listening times.
additionalProperties:
type: integer
description: The total time (in seconds) listened to on that day of the week.
today:
type: integer
description: The time (in seconds) the user has listened to library items today.
recentSessions:
type: array
items:
$ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSession'

266
docs/controllers/SessionController.yaml
View file

@ -18,41 +18,41 @@ paths:
description: The current time of the session.
required: true
schema:
$ref: '../schemas.yaml#/components/schemas/durationSec'
$ref: '../schemas.yaml#/components/schemas/durationSec'
- name: timeListened
in: query
description: The time listened to the session.
required: true
schema:
$ref: '../schemas.yaml#/components/schemas/durationSec'
$ref: '../schemas.yaml#/components/schemas/durationSec'
- name: duration
in: query
description: The duration of the session.
required: true
schema:
$ref: '../schemas.yaml#/components/schemas/durationSec'
$ref: '../schemas.yaml#/components/schemas/durationSec'
responses:
'200':
description: OK
content:
html/text:
schema:
type: string
example: OK
description: OK
content:
html/text:
schema:
type: string
example: OK
'404':
description: No listening session with the provided ID is open, or the session belongs to another user.
content:
html/text:
schema:
type: string
example: Not Found
description: No listening session with the provided ID is open, or the session belongs to another user.
content:
html/text:
schema:
type: string
example: Not Found
'500':
description: There was an error syncing the session.
content:
html/text:
schema:
type: string
example: Internal Server Error
description: There was an error syncing the session.
content:
html/text:
schema:
type: string
example: Internal Server Error
/api/sessions/{id}:
delete:
operationId: deleteSession
@ -69,26 +69,26 @@ paths:
$ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSessionId'
responses:
'200':
description: OK
content:
html/text:
schema:
type: string
example: OK
description: OK
content:
html/text:
schema:
type: string
example: OK
'403':
description: A user with delete permissions is required to delete sessions.
content:
html/text:
schema:
type: string
example: Forbidden
description: A user with delete permissions is required to delete sessions.
content:
html/text:
schema:
type: string
example: Forbidden
'404':
description: No listening session with the provided ID was found.
content:
html/text:
schema:
type: string
example: Not Found
description: No listening session with the provided ID was found.
content:
html/text:
schema:
type: string
example: Not Found
/api/session/{id}/close:
post:
operationId: closeSession
@ -123,103 +123,103 @@ paths:
$ref: '../schemas.yaml#/components/schemas/durationSec'
responses:
'200':
description: OK
content:
html/text:
schema:
type: string
example: OK
description: OK
content:
html/text:
schema:
type: string
example: OK
'404':
description: No listening session with the provided ID is open, or the session belongs to another user.
content:
html/text:
schema:
type: string
example: Not Found
description: No listening session with the provided ID is open, or the session belongs to another user.
content:
html/text:
schema:
type: string
example: Not Found
/api/session/{id}:
get:
operationId: getSession
summary: Get a listening session.
description: Get a listening session.
tags:
- Session
parameters:
- name: id
in: path
description: The ID of the session.
required: true
operationId: getSession
summary: Get a listening session.
description: Get a listening session.
tags:
- Session
parameters:
- name: id
in: path
description: The ID of the session.
required: true
schema:
$ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSessionId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSessionId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSessionExpanded'
'404':
description: No listening session with the provided ID was found.
content:
html/text:
schema:
type: string
example: Not Found
$ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSessionExpanded'
'404':
description: No listening session with the provided ID was found.
content:
html/text:
schema:
type: string
example: Not Found
/api/sessions:
get:
operationId: getSessions
summary: Get all listening sessions.
description: Get all listening sessions.
tags:
- Session
parameters:
- name: user
in: query
description: The ID of the user to filter listening sessions by.
required: false
schema:
$ref: '../objects/entities/User.yaml#/components/schemas/userId'
- name: itemsPerPage
in: query
description: The number of items to return.
required: false
schema:
$ref: '../schemas.yaml#/components/schemas/limit'
- name: page
in: query
description: The page number (zero indexed) to return.
required: false
schema:
$ref: '../schemas.yaml#/components/schemas/page'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
$ref: '../objects/LibraryItem.yaml#/components/schemas/libraryItemBase'
total:
$ref: '../schemas.yaml#/components/schemas/total'
itemsPerPage:
$ref: '../schemas.yaml#/components/schemas/limit'
numPages:
description: The number of pages.
type: integer
example: 10
userFilter:
description: If provided, the `user` parameter.
sessions:
type: array
items:
$ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSession'
'404':
description: No listening sessions were found.
content:
html/text:
schema:
type: string
example: Not Found
operationId: getSessions
summary: Get all listening sessions.
description: Get all listening sessions.
tags:
- Session
parameters:
- name: user
in: query
description: The ID of the user to filter listening sessions by.
required: false
schema:
$ref: '../objects/entities/User.yaml#/components/schemas/userId'
- name: itemsPerPage
in: query
description: The number of items to return.
required: false
schema:
$ref: '../schemas.yaml#/components/schemas/limit'
- name: page
in: query
description: The page number (zero indexed) to return.
required: false
schema:
$ref: '../schemas.yaml#/components/schemas/page'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
$ref: '../objects/LibraryItem.yaml#/components/schemas/libraryItemBase'
total:
$ref: '../schemas.yaml#/components/schemas/total'
itemsPerPage:
$ref: '../schemas.yaml#/components/schemas/limit'
numPages:
description: The number of pages.
type: integer
example: 10
userFilter:
description: If provided, the `user` parameter.
sessions:
type: array
items:
$ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSession'
'404':
description: No listening sessions were found.
content:
html/text:
schema:
type: string
example: Not Found

4
docs/objects/Bookmarks.yaml
View file

@ -7,7 +7,7 @@ components:
bookmark:
properties:
libraryItemId:
$ref: 'LibraryItem.yaml#/components/schemas/libraryItemId'
$ref: './LibraryItem.yaml#/components/schemas/libraryItemId'
title:
type: string
description: The title of the bookmark.
@ -15,4 +15,4 @@ components:
time:
$ref: '#/components/schemas/time'
createdAt:
$ref: '../schemas.yaml#/components/schemas/createdAt'
$ref: '../schemas.yaml#/components/schemas/createdAt'

20
docs/objects/LibraryItem.yaml
View file

@ -67,16 +67,16 @@ components:
media:
$ref: './mediaTypes/media.yaml#/components/schemas/mediaMinified'
libraryItem:
type: object
description: A single item on the server, like a book or podcast.
allOf:
- $ref: '#/components/schemas/libraryItemBase'
- type: object
properties:
libraryFiles:
type: array
items:
$ref: './files/AudioFile.yaml#/components/schemas/libraryFile'
type: object
description: A single item on the server, like a book or podcast.
allOf:
- $ref: '#/components/schemas/libraryItemBase'
- type: object
properties:
libraryFiles:
type: array
items:
$ref: './files/AudioFile.yaml#/components/schemas/libraryFile'
libraryItemSequence:
type: object
description: A single item on the server, like a book or podcast. Includes series sequence information.

70
docs/objects/Media.yaml
View file

@ -5,38 +5,72 @@ components:
description: The ID of the media progress.
example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
format: uuid
progress:
type: number
description: The user's progress in the media item.
example: 0.5
currentTime:
type: number
description: The user's current time in the media item.
example: 0.5
isFinished:
type: boolean
description: Whether the user has finished the media item.
example: false
hideFromContinueListening:
type: boolean
description: Whether the media item should be hidden from the continue listening section.
example: false
finishedAt:
type: integer
nullable: true
description: The time (in ms since POSIX epoch) when the media was finished. Will be null if the media has is not finished.
example: 1616239000
mediaProgress:
type: object
properties:
id:
$ref: '#/components/schemas/mediaProgressId'
libraryItemId:
$ref: 'LibraryItem.yaml#/components/schemas/libraryItemId'
episodeId:
$ref: 'mediaTypes/Podcast.yaml#/components/schemas/podcastId'
$ref: './LibraryItem.yaml#/components/schemas/libraryItemId'
duration:
$ref: '../schemas.yaml#/components/schemas/durationSec'
progress:
type: number
description: The user's progress in the media item.
example: 0.5
$ref: '#/components/schemas/progress'
currentTime:
type: number
description: The user's current time in the media item.
example: 0.5
$ref: '#/components/schemas/currentTime'
isFinished:
type: boolean
description: Whether the user has finished the media item.
example: false
$ref: '#/components/schemas/isFinished'
hideFromContinueListening:
type: boolean
description: Whether the media item should be hidden from the continue listening section.
example: false
$ref: '#/components/schemas/hideFromContinueListening'
lastUpdate:
$ref: '../schemas.yaml#/components/schemas/updatedAt'
startedAt:
$ref: '../schemas.yaml#/components/schemas/createdAt'
finishedAt:
type: integer
description: The time (in ms since POSIX epoch) when the media was finished. Will be null if the media has is not finished.
example: 1616239000
$ref: '#/components/schemas/finishedAt'
mediaProgressPodcastEpisode:
type: object
properties:
id:
$ref: '#/components/schemas/mediaProgressId'
libraryItemId:
$ref: './LibraryItem.yaml#/components/schemas/libraryItemId'
episodeId:
$ref: './mediaTypes/Podcast.yaml#/components/schemas/podcastId'
duration:
$ref: '../schemas.yaml#/components/schemas/durationSec'
progress:
$ref: '#/components/schemas/progress'
currentTime:
$ref: '#/components/schemas/currentTime'
isFinished:
$ref: '#/components/schemas/isFinished'
hideFromContinueListening:
$ref: '#/components/schemas/hideFromContinueListening'
lastUpdate:
$ref: '../schemas.yaml#/components/schemas/updatedAt'
startedAt:
$ref: '../schemas.yaml#/components/schemas/createdAt'
finishedAt:
$ref: '#/components/schemas/finishedAt'

40
docs/objects/entities/Device.yaml
View file

@ -11,32 +11,32 @@ components:
clientName:
description: The client name.
type: string
example: "Audible"
example: 'Audible'
manufacturer:
description: The manufacturer of the device.
type: string
example: "Apple"
example: 'Apple'
model:
description: The model of the device.
type: string
example: "iPhone 12"
description: The model of the device.
type: string
example: 'iPhone 12'
sdkVersion:
description: For an Android client, the Android SDK version of the client.
type: integer
example: 49
deviceInfo:
description: The device information to send to the server.
type: object
properties:
deviceId:
$ref: '#/components/schemas/deviceId'
clientVersion:
$ref: '#/components/schemas/clientVersion'
clientName:
$ref: '#/components/schemas/clientName'
manufacturer:
$ref: '#/components/schemas/manufacturer'
model:
$ref: '#/components/schemas/model'
sdkVersion:
$ref: '#/components/schemas/sdkVersion'
description: The device information to send to the server.
type: object
properties:
deviceId:
$ref: '#/components/schemas/deviceId'
clientVersion:
$ref: '#/components/schemas/clientVersion'
clientName:
$ref: '#/components/schemas/clientName'
manufacturer:
$ref: '#/components/schemas/manufacturer'
model:
$ref: '#/components/schemas/model'
sdkVersion:
$ref: '#/components/schemas/sdkVersion'

81
docs/objects/entities/PlaybackSession.yaml
View file

@ -7,6 +7,17 @@ components:
playbackSession:
type: object
description: A playback session object.
oneOf:
- $ref: '#/components/schemas/playbackSessionBook'
- $ref: '#/components/schemas/playbackSessionPodcast'
discriminator:
propertyName: mediaType
mapping:
book: '#/components/schemas/playbackSessionBook'
podcast: '#/components/schemas/playbackSessionPodcast'
playbackSessionBase:
type: object
description: Base playback session object.
properties:
id:
$ref: '#/components/schemas/playbackSessionId'
@ -16,20 +27,8 @@ components:
$ref: '../Library.yaml#/components/schemas/libraryId'
libraryItemId:
$ref: '../LibraryItem.yaml#/components/schemas/libraryItemId'
episodeId:
$ref: '../mediaTypes/Podcast.yaml#/components/schemas/podcastId'
mediaType:
$ref: '../mediaTypes/media.yaml#/components/schemas/mediaType'
mediaMetadata:
description: The metadata of the media.
oneOf:
- $ref: '../mediaTypes/Book.yaml#/components/schemas/bookMinified'
- $ref: '../mediaTypes/Podcast.yaml#/components/schemas/Podcast'
chapters:
description: The chapters of the media.
type: array
items:
$ref: '../metadata/BookMetadata.yaml#/components/schemas/bookChapter'
displayTitle:
description: The display title of the media.
type: string
@ -66,19 +65,67 @@ components:
$ref: '../../schemas.yaml#/components/schemas/createdAt'
updatedAt:
$ref: '../../schemas.yaml#/components/schemas/updatedAt'
playbackSessionExpanded:
description: Expanded playback session schema.
playbackSessionBook:
description: Book playback session schema.
allOf:
- $ref: '#/components/schemas/playbackSession'
- $ref: '#/components/schemas/playbackSessionBase'
- properties:
mediaMetadata:
$ref: '../metadata/BookMetadata.yaml#/components/schemas/bookMetadata'
chapters:
description: The chapters of the media.
type: array
items:
$ref: '../metadata/BookMetadata.yaml#/components/schemas/bookChapter'
playbackSessionPodcast:
description: Podcast playback session schema.
allOf:
- $ref: '#/components/schemas/playbackSessionBase'
- properties:
mediaMetadata:
$ref: '../metadata/PodcastMetadata.yaml#/components/schemas/PodcastMetadata'
episodeId:
$ref: '../mediaTypes/Podcast.yaml#/components/schemas/podcastId'
playbackSessionExpanded:
type: object
description: A playback session object.
oneOf:
- $ref: '#/components/schemas/playbackSessionBookExpanded'
- $ref: '#/components/schemas/playbackSessionPodcastExpanded'
discriminator:
propertyName: mediaType
mapping:
book: '#/components/schemas/playbackSessionBookExpanded'
podcast: '#/components/schemas/playbackSessionPodcastExpanded'
playbackSessionBookExpanded:
description: Expanded book playback session schema.
allOf:
- $ref: '#/components/schemas/playbackSessionBook'
- properties:
audioTracks:
description: The audio tracks of the media.
type: array
items:
$ref: '../files/AudioTrack.yaml#/components/schemas/AudioTrack'
$ref: '../files/AudioTrack.yaml#/components/schemas/AudioTrack'
videoTrack:
description: The video track of the media. TODO
type: object
nullable: true
libraryItem:
$ref: '../LibraryItem.yaml#/components/schemas/libraryItem'
$ref: '../LibraryItem.yaml#/components/schemas/libraryItem'
playbackSessionPodcastExpanded:
description: Expanded podcast playback session schema.
allOf:
- $ref: '#/components/schemas/playbackSessionPodcast'
- properties:
audioTracks:
description: The audio tracks of the media.
type: array
items:
$ref: '../files/AudioTrack.yaml#/components/schemas/AudioTrack'
videoTrack:
description: The video track of the media. TODO
type: object
nullable: true
libraryItem:
$ref: '../LibraryItem.yaml#/components/schemas/libraryItem'

31
docs/objects/files/AudioFile.yaml
View file

@ -93,19 +93,18 @@ components:
type: string
example: audio/mpeg
libraryFile:
type: object
description: A library file. Includes the path and metadata of the file.
properties:
ino:
$ref: '../../schemas.yaml#/components/schemas/inode'
addedAt:
$ref: '../../schemas.yaml#/components/schemas/addedAt'
updatedAt:
$ref: '../../schemas.yaml#/components/schemas/updatedAt'
fileType:
description: The type of file.
type: string
example: audio
metadata:
$ref: '../metadata/FileMetadata.yaml#/components/schemas/fileMetadata'
type: object
description: A library file. Includes the path and metadata of the file.
properties:
ino:
$ref: '../../schemas.yaml#/components/schemas/inode'
addedAt:
$ref: '../../schemas.yaml#/components/schemas/addedAt'
updatedAt:
$ref: '../../schemas.yaml#/components/schemas/updatedAt'
fileType:
description: The type of file.
type: string
example: audio
metadata:
$ref: '../metadata/FileMetadata.yaml#/components/schemas/fileMetadata'

35
docs/objects/metadata/BookMetadata.yaml
View file

@ -24,7 +24,7 @@ components:
type: array
items:
type: string
example: ["Fantasy", "Sci-Fi", "Nonfiction: History"]
example: ['Fantasy', 'Sci-Fi', 'Nonfiction: History']
publishedYear:
description: The year the book was published. Will be null if unknown.
type: string
@ -44,23 +44,9 @@ components:
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.
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
@ -79,14 +65,14 @@ components:
type: boolean
example: false
abridged:
description: Whether the book is abridged.
type: boolean
example: false
description: Whether the book is abridged.
type: boolean
example: false
bookMetadataMinified:
type: object
description: The minified metadata for a book in the database.
allOf:
- $ref : '#/components/schemas/bookMetadataBase'
- $ref: '#/components/schemas/bookMetadataBase'
- type: object
properties:
titleIgnorePrefix:
@ -141,10 +127,9 @@ components:
narrators:
type: array
items:
type: string
example: Sam Tsoutsouvas
type: string
example: Sam Tsoutsouvas
series:
type: array
items:
$ref: '../entities/Series.yaml#/components/schemas/seriesSequence'

BIN
docs/openapi.json
View file

Binary file not shown.

6
docs/root.yaml
View file

@ -83,14 +83,16 @@ paths:
$ref: './controllers/AuthController.yaml#/paths/~1logout'
/api/items/{id}:
$ref: './controllers/LibraryItemController.yaml#/paths/~1api~1items~1{id}'
/api/items/{id}/play:
$ref: './controllers/LibraryItemController.yaml#/paths/~1api~1items~1{id}~1play'
/api/items/{id}/play/{episodeId}:
$ref: './controllers/LibraryItemController.yaml#/paths/~1api~1items~1{id}~1play~1{episodeId}'
/api/me:
$ref: './controllers/MeController.yaml#/paths/~1api~1me'
/api/me/progress/{libraryItemId}:
$ref: './controllers/MeController.yaml#/paths/~1api~1me~1progress~1{libraryItemId}'
/api/me/progress/{libraryItemId}/{episodeId}:
$ref: './controllers/MeController.yaml#/paths/~1api~1me~1progress~1{libraryItemId}~1{episodeId}'
/api/me/progress/{mediaId}:
$ref: './controllers/MeController.yaml#/paths/~1api~1me~1progress~1{mediaId}'
/api/session/{id}/sync:
$ref: './controllers/SessionController.yaml#/paths/~1api~1session~1{id}~1sync'
/api/sessions/{id}: