- feat: internal/api/openapi/openapi.yaml describes every operation (OpenAPI 3.0.3), written by hand and embedded in the binary; GET /api/v1/openapi.yaml serves it - feat: GET /api/docs/ serves Swagger UI from assets embedded in the binary (github.com/swaggest/swgui, v5emb), so opening it never contacts another server; both are public because they contain no data - feat: response objects in the spec are closed (additionalProperties: false) - test: the spec is valid OpenAPI; the router and the spec describe the same operations in both directions; every operation has an id, a summary, a tag, a documented 401 when it needs a token and a 403 when it is admin only - test: a contract test drives every operation through the real services, including a real scan and real streaming, and validates each response (status, headers, JSON body) against the spec with kin-openapi; it fails if an operation was never exercised. Checked by breaking the code and the spec on purpose - test: the docs page loads without any external address and every asset it references is served - docs: README section on the interactive documentation and on keeping the spec in step with the code Closes #15
1077 lines
36 KiB
YAML
1077 lines
36 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: Sonda API
|
|
version: 0.1.0
|
|
description: |
|
|
Sonda is a privacy-first, self-hosted music server. This is its first-party REST API.
|
|
|
|
**Authentication.** Log in with `POST /auth/login` and send the access token as
|
|
`Authorization: Bearer <token>`. Access tokens are short-lived; renew the session with
|
|
`POST /auth/refresh`. Each refresh token works once.
|
|
|
|
**Roles.** Operations marked *admin* need an account with the admin role. The first user
|
|
who registers is the admin.
|
|
|
|
**Errors.** Every error has the same shape: `{"error": {"code": "...", "message": "..."}}`.
|
|
The `code` is stable and meant for programs; the `message` is for people.
|
|
|
|
**Paging.** Lists take `limit` (default 50, at most 200; a larger value is lowered to 200)
|
|
and `offset`, and answer with `items`, `total`, `limit` and `offset`.
|
|
servers:
|
|
- url: /api/v1
|
|
tags:
|
|
- name: System
|
|
- name: Auth
|
|
description: Accounts and sessions.
|
|
- name: Users
|
|
description: User management (admin).
|
|
- name: Libraries
|
|
description: Named folders of music (admin).
|
|
- name: Scan
|
|
description: Indexing the libraries.
|
|
- name: Catalog
|
|
description: Browsing and searching what can be played.
|
|
- name: Playback
|
|
description: Streaming and listening history.
|
|
|
|
paths:
|
|
/health:
|
|
get:
|
|
tags: [System]
|
|
operationId: getHealth
|
|
summary: Liveness check
|
|
responses:
|
|
'200':
|
|
description: The server is up.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [status]
|
|
properties:
|
|
status: {type: string, enum: [ok]}
|
|
|
|
/openapi.yaml:
|
|
get:
|
|
tags: [System]
|
|
operationId: getOpenAPI
|
|
summary: This document
|
|
responses:
|
|
'200':
|
|
description: The OpenAPI description of the API.
|
|
content:
|
|
application/yaml:
|
|
schema: {type: string}
|
|
|
|
/auth/register:
|
|
post:
|
|
tags: [Auth]
|
|
operationId: register
|
|
summary: Create the first user
|
|
description: |
|
|
Only works while no user exists. The new user is the admin. Afterwards registration is
|
|
closed and admins create accounts with `POST /users`.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Credentials'}
|
|
responses:
|
|
'201':
|
|
description: The admin account.
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/User'}
|
|
'400': {$ref: '#/components/responses/InvalidInput'}
|
|
'403':
|
|
description: A user already exists (`registration_closed`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Error'}
|
|
'409':
|
|
description: The username is taken (`username_taken`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Error'}
|
|
|
|
/auth/login:
|
|
post:
|
|
tags: [Auth]
|
|
operationId: login
|
|
summary: Open a session
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Credentials'}
|
|
responses:
|
|
'200':
|
|
description: A new session.
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Session'}
|
|
'400': {$ref: '#/components/responses/InvalidInput'}
|
|
'401':
|
|
description: Wrong username or password (`invalid_credentials`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Error'}
|
|
|
|
/auth/refresh:
|
|
post:
|
|
tags: [Auth]
|
|
operationId: refresh
|
|
summary: Renew a session
|
|
description: |
|
|
Exchanges a refresh token for a new access token and a new refresh token. The old refresh
|
|
token stops working. Presenting a spent one again, more than ten seconds after it was used,
|
|
ends every session of that user; inside those ten seconds it only fails, so two tabs
|
|
refreshing together do not log each other out.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/RefreshRequest'}
|
|
responses:
|
|
'200':
|
|
description: A new session.
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Session'}
|
|
'400': {$ref: '#/components/responses/InvalidInput'}
|
|
'401':
|
|
description: The refresh token is unknown, expired or already used (`invalid_refresh_token`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Error'}
|
|
|
|
/auth/logout:
|
|
post:
|
|
tags: [Auth]
|
|
operationId: logout
|
|
summary: End a session
|
|
description: Revokes one refresh token. Always answers 204, so it never reveals whether the token existed.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/RefreshRequest'}
|
|
responses:
|
|
'204': {description: Done.}
|
|
'400': {$ref: '#/components/responses/InvalidInput'}
|
|
|
|
/auth/me:
|
|
get:
|
|
tags: [Auth]
|
|
operationId: getMe
|
|
summary: The signed-in account
|
|
security: [{bearerAuth: []}]
|
|
responses:
|
|
'200':
|
|
description: Your account.
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/User'}
|
|
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
|
|
/auth/password:
|
|
post:
|
|
tags: [Auth]
|
|
operationId: changePassword
|
|
summary: Change your password
|
|
description: "Signs you out everywhere: every refresh token of the account is revoked."
|
|
security: [{bearerAuth: []}]
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/PasswordChange'}
|
|
responses:
|
|
'204': {description: Password changed.}
|
|
'400': {$ref: '#/components/responses/InvalidInput'}
|
|
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
'403':
|
|
description: The current password is wrong (`invalid_credentials`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Error'}
|
|
|
|
/users:
|
|
get:
|
|
tags: [Users]
|
|
operationId: listUsers
|
|
summary: List users
|
|
description: Admin only.
|
|
security: [{bearerAuth: []}]
|
|
responses:
|
|
'200':
|
|
description: Every account, oldest first.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [users]
|
|
properties:
|
|
users:
|
|
type: array
|
|
items: {$ref: '#/components/schemas/User'}
|
|
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
'403': {$ref: '#/components/responses/AdminRequired'}
|
|
post:
|
|
tags: [Users]
|
|
operationId: createUser
|
|
summary: Create a user
|
|
description: Admin only.
|
|
security: [{bearerAuth: []}]
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/CreateUser'}
|
|
responses:
|
|
'201':
|
|
description: The new account.
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/User'}
|
|
'400': {$ref: '#/components/responses/InvalidInput'}
|
|
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
'403': {$ref: '#/components/responses/AdminRequired'}
|
|
'409':
|
|
description: The username is taken (`username_taken`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Error'}
|
|
|
|
/users/{id}:
|
|
parameters:
|
|
- {$ref: '#/components/parameters/Id'}
|
|
patch:
|
|
tags: [Users]
|
|
operationId: updateUser
|
|
summary: Grant or remove the admin role
|
|
description: Admin only. The last admin cannot be demoted.
|
|
security: [{bearerAuth: []}]
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [is_admin]
|
|
properties:
|
|
is_admin: {type: boolean}
|
|
responses:
|
|
'200':
|
|
description: The updated account.
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/User'}
|
|
'400': {$ref: '#/components/responses/InvalidInput'}
|
|
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
'403': {$ref: '#/components/responses/AdminRequired'}
|
|
'404':
|
|
description: No such user (`user_not_found`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Error'}
|
|
'409':
|
|
description: This is the last admin (`last_admin`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Error'}
|
|
delete:
|
|
tags: [Users]
|
|
operationId: deleteUser
|
|
summary: Delete a user
|
|
description: Admin only. Removes the account and its sessions. The last admin cannot be deleted.
|
|
security: [{bearerAuth: []}]
|
|
responses:
|
|
'204': {description: Deleted.}
|
|
'400': {$ref: '#/components/responses/InvalidInput'}
|
|
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
'403': {$ref: '#/components/responses/AdminRequired'}
|
|
'404':
|
|
description: No such user (`user_not_found`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Error'}
|
|
'409':
|
|
description: This is the last admin (`last_admin`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Error'}
|
|
|
|
/users/{id}/password:
|
|
parameters:
|
|
- {$ref: '#/components/parameters/Id'}
|
|
put:
|
|
tags: [Users]
|
|
operationId: resetUserPassword
|
|
summary: Reset a user's password
|
|
description: Admin only. Signs that user out everywhere.
|
|
security: [{bearerAuth: []}]
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [password]
|
|
properties:
|
|
password: {type: string, format: password, minLength: 8, maxLength: 256}
|
|
responses:
|
|
'204': {description: Password reset.}
|
|
'400': {$ref: '#/components/responses/InvalidInput'}
|
|
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
'403': {$ref: '#/components/responses/AdminRequired'}
|
|
'404':
|
|
description: No such user (`user_not_found`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Error'}
|
|
|
|
/libraries:
|
|
get:
|
|
tags: [Libraries]
|
|
operationId: listLibraries
|
|
summary: List libraries
|
|
description: Admin only.
|
|
security: [{bearerAuth: []}]
|
|
responses:
|
|
'200':
|
|
description: Every library, oldest first.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [libraries]
|
|
properties:
|
|
libraries:
|
|
type: array
|
|
items: {$ref: '#/components/schemas/Library'}
|
|
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
'403': {$ref: '#/components/responses/AdminRequired'}
|
|
post:
|
|
tags: [Libraries]
|
|
operationId: createLibrary
|
|
summary: Add a library
|
|
description: |
|
|
Admin only. The path must be an absolute, existing directory, never the filesystem root,
|
|
and never inside or around another library. Names are unique ignoring case.
|
|
security: [{bearerAuth: []}]
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/NewLibrary'}
|
|
responses:
|
|
'201':
|
|
description: The new library.
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Library'}
|
|
'400': {$ref: '#/components/responses/InvalidInput'}
|
|
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
'403': {$ref: '#/components/responses/AdminRequired'}
|
|
'409':
|
|
description: Another library has this name or path (`library_exists`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Error'}
|
|
|
|
/libraries/{id}:
|
|
parameters:
|
|
- {$ref: '#/components/parameters/Id'}
|
|
patch:
|
|
tags: [Libraries]
|
|
operationId: updateLibrary
|
|
summary: Rename or move a library
|
|
description: |
|
|
Admin only. Send `name`, `path` or both. Files keep their identity when the path changes.
|
|
Changing the path is refused while a scan runs.
|
|
security: [{bearerAuth: []}]
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/LibraryUpdate'}
|
|
responses:
|
|
'200':
|
|
description: The updated library.
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Library'}
|
|
'400': {$ref: '#/components/responses/InvalidInput'}
|
|
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
'403': {$ref: '#/components/responses/AdminRequired'}
|
|
'404': {$ref: '#/components/responses/LibraryNotFound'}
|
|
'409':
|
|
description: The name or path is used by another library (`library_exists`), or a scan is running (`scan_running`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Error'}
|
|
delete:
|
|
tags: [Libraries]
|
|
operationId: deleteLibrary
|
|
summary: Remove a library
|
|
description: |
|
|
Admin only. Removes the library and its index entries. Tracks and listening history stay;
|
|
the music on disk is never touched. Refused while a scan runs.
|
|
security: [{bearerAuth: []}]
|
|
responses:
|
|
'204': {description: Removed.}
|
|
'400': {$ref: '#/components/responses/InvalidInput'}
|
|
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
'403': {$ref: '#/components/responses/AdminRequired'}
|
|
'404': {$ref: '#/components/responses/LibraryNotFound'}
|
|
'409':
|
|
description: A scan is running (`scan_running`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Error'}
|
|
|
|
/libraries/{id}/scan:
|
|
parameters:
|
|
- {$ref: '#/components/parameters/Id'}
|
|
post:
|
|
tags: [Scan]
|
|
operationId: scanLibrary
|
|
summary: Scan one library
|
|
description: Admin only. Starts a scan in the background; follow it with `GET /library/scan`.
|
|
security: [{bearerAuth: []}]
|
|
responses:
|
|
'202': {$ref: '#/components/responses/ScanStarted'}
|
|
'400': {$ref: '#/components/responses/InvalidInput'}
|
|
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
'403': {$ref: '#/components/responses/AdminRequired'}
|
|
'404': {$ref: '#/components/responses/LibraryNotFound'}
|
|
'409':
|
|
description: A scan is already running (`scan_running`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Error'}
|
|
|
|
/library/scan:
|
|
get:
|
|
tags: [Scan]
|
|
operationId: getScanStatus
|
|
summary: Scan status
|
|
description: Whether a scan is running and how the last one ended.
|
|
security: [{bearerAuth: []}]
|
|
responses:
|
|
'200':
|
|
description: The current state.
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/ScanStatus'}
|
|
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
post:
|
|
tags: [Scan]
|
|
operationId: scanAll
|
|
summary: Scan every library
|
|
description: |
|
|
Admin only. Starts a scan in the background. Only MP3 and FLAC files are read; other audio
|
|
formats are counted as `unsupported`. Housekeeping folders of NAS boxes (`@Recycle`,
|
|
`#recycle`, `@eaDir`, `.@__thumb`, `$RECYCLE.BIN`) are skipped.
|
|
security: [{bearerAuth: []}]
|
|
responses:
|
|
'202': {$ref: '#/components/responses/ScanStarted'}
|
|
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
'403': {$ref: '#/components/responses/AdminRequired'}
|
|
'409':
|
|
description: A scan is already running (`scan_running`), or there is no library yet (`no_libraries`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Error'}
|
|
|
|
/artists:
|
|
get:
|
|
tags: [Catalog]
|
|
operationId: listArtists
|
|
summary: List artists
|
|
description: |
|
|
Artists credited on a playable track, or that are the album artist of an album with one.
|
|
Sorted by name.
|
|
security: [{bearerAuth: []}]
|
|
parameters:
|
|
- {$ref: '#/components/parameters/Q'}
|
|
- {$ref: '#/components/parameters/Limit'}
|
|
- {$ref: '#/components/parameters/Offset'}
|
|
- {$ref: '#/components/parameters/LibraryId'}
|
|
responses:
|
|
'200':
|
|
description: A page of artists.
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/ArtistPage'}
|
|
'400': {$ref: '#/components/responses/InvalidInput'}
|
|
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
|
|
/artists/{id}:
|
|
parameters:
|
|
- {$ref: '#/components/parameters/Id'}
|
|
get:
|
|
tags: [Catalog]
|
|
operationId: getArtist
|
|
summary: One artist
|
|
security: [{bearerAuth: []}]
|
|
responses:
|
|
'200':
|
|
description: The artist.
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Artist'}
|
|
'400': {$ref: '#/components/responses/InvalidInput'}
|
|
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
'404':
|
|
description: No such artist, or nothing of it can be played (`artist_not_found`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Error'}
|
|
|
|
/albums:
|
|
get:
|
|
tags: [Catalog]
|
|
operationId: listAlbums
|
|
summary: List albums
|
|
description: |
|
|
Albums with a playable track, sorted by title. `artist_id` matches the albums an artist
|
|
owns plus those where it is credited on a playable track, the same set as its `album_count`.
|
|
security: [{bearerAuth: []}]
|
|
parameters:
|
|
- {$ref: '#/components/parameters/Q'}
|
|
- {$ref: '#/components/parameters/Limit'}
|
|
- {$ref: '#/components/parameters/Offset'}
|
|
- {$ref: '#/components/parameters/LibraryId'}
|
|
- {$ref: '#/components/parameters/ArtistId'}
|
|
responses:
|
|
'200':
|
|
description: A page of albums.
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/AlbumPage'}
|
|
'400': {$ref: '#/components/responses/InvalidInput'}
|
|
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
|
|
/albums/{id}:
|
|
parameters:
|
|
- {$ref: '#/components/parameters/Id'}
|
|
get:
|
|
tags: [Catalog]
|
|
operationId: getAlbum
|
|
summary: One album
|
|
security: [{bearerAuth: []}]
|
|
responses:
|
|
'200':
|
|
description: The album.
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Album'}
|
|
'400': {$ref: '#/components/responses/InvalidInput'}
|
|
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
'404':
|
|
description: No such album, or nothing of it can be played (`album_not_found`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Error'}
|
|
|
|
/tracks:
|
|
get:
|
|
tags: [Catalog]
|
|
operationId: listTracks
|
|
summary: List tracks
|
|
description: |
|
|
Tracks with at least one file that is not flagged missing; a track with several files
|
|
appears once. Grouped by album, then disc and track number.
|
|
security: [{bearerAuth: []}]
|
|
parameters:
|
|
- {$ref: '#/components/parameters/Q'}
|
|
- {$ref: '#/components/parameters/Limit'}
|
|
- {$ref: '#/components/parameters/Offset'}
|
|
- {$ref: '#/components/parameters/LibraryId'}
|
|
- {$ref: '#/components/parameters/ArtistId'}
|
|
- {$ref: '#/components/parameters/AlbumId'}
|
|
responses:
|
|
'200':
|
|
description: A page of tracks.
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/TrackPage'}
|
|
'400': {$ref: '#/components/responses/InvalidInput'}
|
|
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
|
|
/tracks/{id}:
|
|
parameters:
|
|
- {$ref: '#/components/parameters/Id'}
|
|
get:
|
|
tags: [Catalog]
|
|
operationId: getTrack
|
|
summary: One track
|
|
security: [{bearerAuth: []}]
|
|
responses:
|
|
'200':
|
|
description: The track.
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Track'}
|
|
'400': {$ref: '#/components/responses/InvalidInput'}
|
|
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
'404':
|
|
description: No such track, or it has no playable file (`track_not_found`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Error'}
|
|
|
|
/tracks/{id}/stream:
|
|
parameters:
|
|
- {$ref: '#/components/parameters/Id'}
|
|
get:
|
|
tags: [Playback]
|
|
operationId: streamTrack
|
|
summary: Stream a track
|
|
description: |
|
|
Serves the original audio file. Supports `Range` requests, so players can seek, and
|
|
conditional requests. Streaming never records a listen; report one with `POST /listens`.
|
|
|
|
An `<audio>` element cannot send headers, so this is the only operation that also accepts
|
|
the access token as the `access_token` query parameter. A header, when present, always wins.
|
|
security:
|
|
- bearerAuth: []
|
|
- streamQueryToken: []
|
|
parameters:
|
|
- name: Range
|
|
in: header
|
|
required: false
|
|
description: A byte range, for example `bytes=0-99`.
|
|
schema: {type: string}
|
|
- name: If-Modified-Since
|
|
in: header
|
|
required: false
|
|
schema: {type: string}
|
|
responses:
|
|
'200':
|
|
description: The whole file.
|
|
headers:
|
|
Accept-Ranges: {$ref: '#/components/headers/AcceptRanges'}
|
|
Content-Length: {$ref: '#/components/headers/ContentLength'}
|
|
Last-Modified: {$ref: '#/components/headers/LastModified'}
|
|
content:
|
|
audio/mpeg:
|
|
schema: {type: string, format: binary}
|
|
audio/flac:
|
|
schema: {type: string, format: binary}
|
|
'206':
|
|
description: The requested byte range.
|
|
headers:
|
|
Content-Range:
|
|
description: The range sent and the size of the file, for example `bytes 0-99/40635`.
|
|
schema: {type: string}
|
|
content:
|
|
audio/mpeg:
|
|
schema: {type: string, format: binary}
|
|
audio/flac:
|
|
schema: {type: string, format: binary}
|
|
'304': {description: Not modified since `If-Modified-Since`.}
|
|
'400': {$ref: '#/components/responses/InvalidInput'}
|
|
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
'404':
|
|
description: No such track (`track_not_found`), or its file is not available (`file_missing`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Error'}
|
|
'416':
|
|
description: The range cannot be satisfied.
|
|
headers:
|
|
Content-Range:
|
|
description: '`bytes */<size of the file>`.'
|
|
schema: {type: string}
|
|
head:
|
|
tags: [Playback]
|
|
operationId: headTrackStream
|
|
summary: Headers of a stream
|
|
description: Same as `GET`, without the body.
|
|
security:
|
|
- bearerAuth: []
|
|
- streamQueryToken: []
|
|
parameters:
|
|
- name: Range
|
|
in: header
|
|
required: false
|
|
schema: {type: string}
|
|
responses:
|
|
'200':
|
|
description: Headers of the whole file.
|
|
headers:
|
|
Accept-Ranges: {$ref: '#/components/headers/AcceptRanges'}
|
|
Content-Length: {$ref: '#/components/headers/ContentLength'}
|
|
Last-Modified: {$ref: '#/components/headers/LastModified'}
|
|
'206':
|
|
description: Headers of the requested range.
|
|
headers:
|
|
Content-Range:
|
|
schema: {type: string}
|
|
'400': {$ref: '#/components/responses/InvalidInput'}
|
|
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
'404': {description: No such track or file.}
|
|
'416': {description: The range cannot be satisfied.}
|
|
|
|
/listens:
|
|
post:
|
|
tags: [Playback]
|
|
operationId: recordListen
|
|
summary: Record a listen
|
|
description: |
|
|
Clients report what the listener did. The `idempotency_key` makes a retry harmless: the
|
|
same key from the same user is recorded once and answered with `duplicate`.
|
|
security: [{bearerAuth: []}]
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Listen'}
|
|
responses:
|
|
'201':
|
|
description: Recorded.
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/ListenResult'}
|
|
'200':
|
|
description: Already recorded (same `idempotency_key`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/ListenResult'}
|
|
'400': {$ref: '#/components/responses/InvalidInput'}
|
|
'401': {$ref: '#/components/responses/Unauthorized'}
|
|
'404':
|
|
description: No such track (`track_not_found`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Error'}
|
|
|
|
components:
|
|
securitySchemes:
|
|
bearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
description: The `access_token` from `POST /auth/login` or `POST /auth/refresh`.
|
|
streamQueryToken:
|
|
type: apiKey
|
|
in: query
|
|
name: access_token
|
|
description: The same access token, for stream URLs used by an `<audio>` element. Accepted only on `/tracks/{id}/stream`.
|
|
|
|
parameters:
|
|
Id:
|
|
name: id
|
|
in: path
|
|
required: true
|
|
schema: {type: integer, format: int64, minimum: 1}
|
|
Q:
|
|
name: q
|
|
in: query
|
|
description: |
|
|
Case-insensitive substring of the name or title. Accented letters are matched ignoring
|
|
case (`BJÖRK` finds `Björk`), but accents are kept (`bjork` does not). At most 200 characters.
|
|
schema: {type: string, maxLength: 200}
|
|
Limit:
|
|
name: limit
|
|
in: query
|
|
description: Page size. Default 50; values above 200 are lowered to 200.
|
|
schema: {type: integer, minimum: 0}
|
|
Offset:
|
|
name: offset
|
|
in: query
|
|
schema: {type: integer, minimum: 0, default: 0}
|
|
LibraryId:
|
|
name: library_id
|
|
in: query
|
|
description: Only items with a playable file in this library.
|
|
schema: {type: integer, format: int64, minimum: 1}
|
|
ArtistId:
|
|
name: artist_id
|
|
in: query
|
|
schema: {type: integer, format: int64, minimum: 1}
|
|
AlbumId:
|
|
name: album_id
|
|
in: query
|
|
schema: {type: integer, format: int64, minimum: 1}
|
|
|
|
headers:
|
|
AcceptRanges:
|
|
description: Always `bytes`.
|
|
schema: {type: string}
|
|
ContentLength:
|
|
schema: {type: integer}
|
|
LastModified:
|
|
schema: {type: string}
|
|
|
|
responses:
|
|
InvalidInput:
|
|
description: The request is malformed or a value is out of range (`invalid_input`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Error'}
|
|
Unauthorized:
|
|
description: The access token is missing, invalid or expired (`unauthorized`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Error'}
|
|
AdminRequired:
|
|
description: The account is not an admin (`admin_required`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Error'}
|
|
LibraryNotFound:
|
|
description: No such library (`library_not_found`).
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/Error'}
|
|
ScanStarted:
|
|
description: The scan was started in the background.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [status]
|
|
properties:
|
|
status: {type: string, enum: [started]}
|
|
|
|
schemas:
|
|
Error:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [error]
|
|
properties:
|
|
error:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [code, message]
|
|
properties:
|
|
code:
|
|
type: string
|
|
description: |
|
|
A stable identifier, for example `invalid_input`, `unauthorized`, `admin_required`,
|
|
`user_not_found`, `last_admin`, `library_exists`, `scan_running`, `track_not_found`.
|
|
message: {type: string}
|
|
|
|
Credentials:
|
|
type: object
|
|
required: [username, password]
|
|
properties:
|
|
username:
|
|
type: string
|
|
minLength: 3
|
|
maxLength: 64
|
|
pattern: '^[A-Za-z0-9._-]+$'
|
|
password: {type: string, format: password, minLength: 8, maxLength: 256}
|
|
|
|
CreateUser:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Credentials'
|
|
- type: object
|
|
properties:
|
|
is_admin: {type: boolean, default: false}
|
|
|
|
User:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [id, username, is_admin]
|
|
properties:
|
|
id: {type: integer, format: int64}
|
|
username: {type: string}
|
|
is_admin: {type: boolean}
|
|
|
|
Session:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [access_token, access_expires_at, refresh_token, refresh_expires_at, user]
|
|
properties:
|
|
access_token: {type: string}
|
|
access_expires_at: {type: string, format: date-time}
|
|
refresh_token: {type: string, description: Works once.}
|
|
refresh_expires_at: {type: string, format: date-time}
|
|
user: {$ref: '#/components/schemas/User'}
|
|
|
|
RefreshRequest:
|
|
type: object
|
|
required: [refresh_token]
|
|
properties:
|
|
refresh_token: {type: string}
|
|
|
|
PasswordChange:
|
|
type: object
|
|
required: [current_password, new_password]
|
|
properties:
|
|
current_password: {type: string, format: password}
|
|
new_password: {type: string, format: password, minLength: 8, maxLength: 256}
|
|
|
|
Library:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [id, name, path, created_at]
|
|
properties:
|
|
id: {type: integer, format: int64}
|
|
name: {type: string}
|
|
path: {type: string, description: Absolute directory on the server.}
|
|
created_at: {type: string, format: date-time}
|
|
|
|
NewLibrary:
|
|
type: object
|
|
required: [name, path]
|
|
properties:
|
|
name: {type: string, minLength: 1, maxLength: 100}
|
|
path: {type: string, description: "Absolute, existing directory."}
|
|
|
|
LibraryUpdate:
|
|
type: object
|
|
minProperties: 1
|
|
properties:
|
|
name: {type: string, minLength: 1, maxLength: 100}
|
|
path: {type: string}
|
|
|
|
ScanSummary:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [libraries, found, added, updated, unchanged, renamed, restored, missing, failed, skipped, unsupported]
|
|
properties:
|
|
libraries: {type: integer, description: Libraries covered by the scan.}
|
|
found: {type: integer, description: Audio files seen on disk (MP3 and FLAC).}
|
|
added: {type: integer}
|
|
updated: {type: integer}
|
|
unchanged: {type: integer}
|
|
renamed: {type: integer, description: Files that moved; they keep their track.}
|
|
restored: {type: integer, description: Files that were missing and are back.}
|
|
missing: {type: integer, description: Files newly flagged as missing. They are never deleted.}
|
|
failed: {type: integer, description: Files that could not be read.}
|
|
skipped: {type: integer, description: Symlinks and special files.}
|
|
unsupported: {type: integer, description: "Audio files in formats Sonda cannot read yet, such as m4a, ogg or wav."}
|
|
|
|
ScanStatus:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [running]
|
|
properties:
|
|
running: {type: boolean}
|
|
started_at: {type: string, format: date-time}
|
|
last_finished_at: {type: string, format: date-time}
|
|
last: {$ref: '#/components/schemas/ScanSummary'}
|
|
last_error: {type: string}
|
|
|
|
ArtistRef:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [id, name]
|
|
properties:
|
|
id: {type: integer, format: int64}
|
|
name: {type: string}
|
|
|
|
AlbumRef:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [id, title]
|
|
properties:
|
|
id: {type: integer, format: int64}
|
|
title: {type: string}
|
|
|
|
Artist:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [id, name, album_count, track_count]
|
|
properties:
|
|
id: {type: integer, format: int64}
|
|
name: {type: string}
|
|
album_count: {type: integer}
|
|
track_count: {type: integer, description: Playable tracks the artist is credited on.}
|
|
|
|
Album:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [id, title, artist, track_count, duration_ms]
|
|
properties:
|
|
id: {type: integer, format: int64}
|
|
title: {type: string}
|
|
artist:
|
|
nullable: true
|
|
description: The album artist, if the album has one.
|
|
allOf:
|
|
- $ref: '#/components/schemas/ArtistRef'
|
|
track_count: {type: integer}
|
|
duration_ms: {type: integer, format: int64}
|
|
|
|
Track:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [id, title, duration_ms, track_no, disc_no, album, artists, format]
|
|
properties:
|
|
id: {type: integer, format: int64}
|
|
title: {type: string}
|
|
duration_ms: {type: integer, format: int64}
|
|
track_no: {type: integer, description: 0 when unknown.}
|
|
disc_no: {type: integer, description: 0 when unknown.}
|
|
album:
|
|
nullable: true
|
|
allOf:
|
|
- $ref: '#/components/schemas/AlbumRef'
|
|
artists:
|
|
type: array
|
|
items: {$ref: '#/components/schemas/ArtistRef'}
|
|
format: {type: string, description: 'Format of the first playable file, for example `mp3` or `flac`.'}
|
|
|
|
ArtistPage:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [items, total, limit, offset]
|
|
properties:
|
|
items:
|
|
type: array
|
|
items: {$ref: '#/components/schemas/Artist'}
|
|
total: {type: integer, description: "Size of the whole result, not of this page."}
|
|
limit: {type: integer}
|
|
offset: {type: integer}
|
|
|
|
AlbumPage:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [items, total, limit, offset]
|
|
properties:
|
|
items:
|
|
type: array
|
|
items: {$ref: '#/components/schemas/Album'}
|
|
total: {type: integer}
|
|
limit: {type: integer}
|
|
offset: {type: integer}
|
|
|
|
TrackPage:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [items, total, limit, offset]
|
|
properties:
|
|
items:
|
|
type: array
|
|
items: {$ref: '#/components/schemas/Track'}
|
|
total: {type: integer}
|
|
limit: {type: integer}
|
|
offset: {type: integer}
|
|
|
|
Listen:
|
|
type: object
|
|
required: [track_id, event_type, idempotency_key]
|
|
properties:
|
|
track_id: {type: integer, format: int64, minimum: 1}
|
|
event_type: {type: string, enum: [play, complete, skip]}
|
|
occurred_at: {type: string, format: date-time, description: Defaults to now.}
|
|
duration_played_ms: {type: integer, format: int64, minimum: 0}
|
|
idempotency_key: {type: string, minLength: 1, maxLength: 128}
|
|
|
|
ListenResult:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [status]
|
|
properties:
|
|
status: {type: string, enum: [recorded, duplicate]}
|