polaris-mirror/docs/swagger/polaris-api.json
2020-01-11 01:58:22 -08:00

1037 lines
No EOL
35 KiB
JSON

{
"openapi": "3.0.0",
"info": {
"description": "",
"version": "3.0",
"title": "Polaris",
"termsOfService": ""
},
"servers": [
{
"url": "/api"
}
],
"tags": [
{
"name": "Collection",
"description": "Browsing the music collection"
},
{
"name": "Last.fm",
"description": "Integrating with Last.fm"
},
{
"name": "Settings",
"description": "Managing the polaris installation"
},
{
"name": "Playlists",
"description": "Managing playlists"
},
{
"name": "Other"
}
],
"paths": {
"/version": {
"get": {
"tags": [
"Other"
],
"summary": "Returns which API version this server implements",
"operationId": "getVersion",
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Version"
}
}
}
}
}
}
},
"/initial_setup": {
"get": {
"tags": [
"Other"
],
"summary": "Returns the current state of the initial setup flow",
"operationId": "getInitialSetup",
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitialSetup"
}
}
}
}
}
}
},
"/trigger_index": {
"post": {
"tags": [
"Other"
],
"summary": "Begins or queues a crawl of the music collection",
"operationId": "postTriggerIndex",
"responses": {
"200": {
"description": "Successful operation"
}
},
"security": [
{
"admin_http_header": [],
"admin_cookie": []
}
]
}
},
"/settings": {
"get": {
"tags": [
"Settings"
],
"summary": "Reads the existing server configuration",
"operationId": "getSettings",
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#components/schemas/Config"
}
}
}
}
},
"security": [
{
"admin_http_header": [],
"admin_cookie": []
}
]
},
"put": {
"tags": [
"Settings"
],
"summary": "Overwrites the server configuration",
"operationId": "getSettings",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#components/schemas/Config"
}
}
}
},
"responses": {
"200": {
"description": "Successful operation"
}
},
"security": [
{
"admin_http_header": [],
"admin_cookie": []
}
]
}
},
"/preferences": {
"get": {
"tags": [
"Settings"
],
"summary": "Reads the preferences of the current user",
"operationId": "getPreferences",
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#components/schemas/Preferences"
}
}
}
}
},
"security": [
{
"auth_http_header": [],
"auth_cookie": []
}
]
}
},
"/auth": {
"post": {
"tags": [
"Other"
],
"summary": "Returns information about user permissions and a session cookie for future authenticated requests.",
"operationId": "postAuth",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#components/schemas/AuthCredentials"
}
}
}
},
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#components/schemas/AuthOutput"
}
}
}
},
"401": {
"description": "Invalid credentials"
}
}
}
},
"/browse": {
"get": {
"tags": [
"Collection"
],
"summary": "Reads the content of the top-level directory in the music collection",
"operationId": "getBrowse",
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CollectionFile"
}
}
}
}
}
},
"security": [
{
"auth_http_header": [],
"auth_cookie": []
}
]
}
},
"/browse/{location}": {
"get": {
"tags": [
"Collection"
],
"summary": "Reads the content of a directory in the music collection",
"operationId": "getBrowsePath",
"parameters": [
{
"name": "location",
"in": "path",
"description": "Path to the collection directory begin explored",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CollectionFile"
}
}
}
}
}
},
"security": [
{
"auth_http_header": [],
"auth_cookie": []
}
]
}
},
"/flatten": {
"get": {
"tags": [
"Collection"
],
"summary": "Recursively lists all the songs in the music collection",
"operationId": "getFlatten",
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Song"
}
}
}
}
}
},
"security": [
{
"auth_http_header": [],
"auth_cookie": []
}
]
}
},
"/flatten/{location}": {
"get": {
"tags": [
"Collection"
],
"summary": "Recursively lists all the songs within a directory of the music collection",
"operationId": "getFlattenPath",
"parameters": [
{
"name": "location",
"in": "path",
"description": "Path to the collection directory begin explored",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Song"
}
}
}
}
}
},
"security": [
{
"auth_http_header": [],
"auth_cookie": []
}
]
}
},
"/random": {
"get": {
"tags": [
"Collection"
],
"summary": "Returns a list of random albums",
"operationId": "getRandom",
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Directory"
}
}
}
}
}
},
"security": [
{
"auth_http_header": [],
"auth_cookie": []
}
]
}
},
"/recent": {
"get": {
"tags": [
"Collection"
],
"summary": "Returns the albums most recently added to the collection",
"operationId": "getRecent",
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Directory"
}
}
}
}
}
},
"security": [
{
"auth_http_header": [],
"auth_cookie": []
}
]
}
},
"/search/{query}": {
"get": {
"tags": [
"Collection"
],
"summary": "Searches for songs and directories",
"operationId": "getSearch",
"parameters": [
{
"name": "query",
"in": "path",
"description": "Search query used to filter results",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CollectionFile"
}
}
}
}
}
},
"security": [
{
"auth_http_header": [],
"auth_cookie": []
}
]
}
},
"/serve/{file}": {
"get": {
"tags": [
"Collection"
],
"summary": "Access a media file in the collection",
"operationId": "getServe",
"parameters": [
{
"name": "file",
"in": "path",
"description": "Path to the desired file",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"image/*": {
"schema": {
"format": "binary"
}
},
"audio/*": {
"schema": {
"format": "binary"
}
}
}
}
},
"security": [
{
"auth_http_header": [],
"auth_cookie": []
}
]
}
},
"/playlists": {
"get": {
"tags": [
"Playlists"
],
"summary": "Lists the playlists belonging to the current user",
"operationId": "getPlaylists",
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ListPlaylistsEntry"
}
}
}
}
}
},
"security": [
{
"auth_http_header": [],
"auth_cookie": []
}
]
}
},
"/playlist/{playlistName}": {
"get": {
"tags": [
"Playlists"
],
"summary": "Reads the content of a playlist",
"operationId": "getPlaylist",
"parameters": [
{
"name": "playlistName",
"in": "path",
"description": "Name of the playlist to read",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Song"
}
}
}
}
}
},
"security": [
{
"auth_http_header": [],
"auth_cookie": []
}
]
},
"put": {
"tags": [
"Playlists"
],
"summary": "Saves a playlist",
"operationId": "putPlaylist",
"parameters": [
{
"name": "playlistName",
"in": "path",
"description": "Name of the playlist to save",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SavePlaylistInput"
}
}
}
},
"responses": {
"200": {
"description": "Successful operation"
}
},
"security": [
{
"auth_http_header": [],
"auth_cookie": []
}
]
},
"delete": {
"tags": [
"Playlists"
],
"summary": "Deletes a playlist",
"operationId": "deletePlaylist",
"parameters": [
{
"name": "playlistName",
"in": "path",
"description": "Name of the playlist to delete",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful operation"
}
},
"security": [
{
"auth_http_header": [],
"auth_cookie": []
}
]
}
},
"/lastfm/now_playing/{song}": {
"put": {
"tags": [
"Last.fm"
],
"summary": "Tells Last.fm the song currently being played",
"operationId": "putLastFMNowPlaying",
"parameters": [
{
"name": "song",
"in": "path",
"description": "Path to the song being played",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful operation"
}
},
"security": [
{
"auth_http_header": [],
"auth_cookie": []
}
]
}
},
"/lastfm/scrobble/{song}": {
"post": {
"tags": [
"Last.fm"
],
"summary": "Tells Last.fm that a song has been playing for long enough to be scrobbled",
"operationId": "postLastFMScrobble",
"parameters": [
{
"name": "song",
"in": "path",
"description": "Path to the song being played",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful operation"
}
},
"security": [
{
"auth_http_header": [],
"auth_cookie": []
}
]
}
},
"/lastfm/link": {
"get": {
"tags": [
"Last.fm"
],
"summary": "Links a Polaris user with a Last.fm account.",
"externalDocs": {
"description": "This endpoint is meant to be used as a Last.fm authentication handler, as described here:",
"url": "https://www.last.fm/api/webauth"
},
"operationId": "getLastFMLink",
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"description": "Last.fm authentication token",
"schema": {
"type": "string"
}
},
{
"name": "content",
"in": "query",
"required": true,
"description": "Base64 encoded HTML content to be returned to the client initiating the link operation",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"text/html": {
"description": "The same content originally present in the 'content' parameter"
}
}
}
}
},
"delete": {
"tags": [
"Last.fm"
],
"summary": "Unlinks Polaris user and Last.fm account",
"operationId": "deleteLastFMLink",
"responses": {
"200": {
"description": "Successful operation"
}
},
"security": [
{
"auth_http_header": [],
"auth_cookie": []
}
]
}
}
},
"components": {
"schemas": {
"Version": {
"type": "object",
"properties": {
"major": {
"type": "integer",
"format": "int64",
"example": 3
},
"minor": {
"type": "integer",
"format": "int64",
"example": 0
}
}
},
"InitialSetup": {
"type": "object",
"properties": {
"has_any_users": {
"type": "boolean"
}
}
},
"Config": {
"type": "object",
"properties": {
"album_art_pattern": {
"type": "string",
"example": "^Folder.(png|jpg|jpeg)$"
},
"reindex_every_n_seconds": {
"type": "integer",
"example": 3600
},
"mount_dirs": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MountPoint"
}
},
"prefix_url": {
"type": "string"
},
"users": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ConfigUser"
}
},
"ydns": {
"type": "object",
"properties": {
"host": {
"type": "string",
"example": "yourname.ydns.eu"
},
"username": {
"type": "string",
"example": "you@host.com"
},
"password": {
"type": "string",
"example": "hunter2"
}
}
}
}
},
"ConfigUser": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"password": {
"type": "string",
"description": "Always blank when this field appear in a server response"
},
"admin": {
"type": "boolean"
}
}
},
"MountPoint": {
"type": "object",
"properties": {
"source": {
"type": "string",
"example": "/mnt/some_drive/music"
},
"name": {
"type": "string",
"example": "My Music"
}
}
},
"Preferences": {
"type": "object",
"properties": {
"lastfm_username": {
"type": "string"
},
"web_theme_base": {
"type": "string"
},
"web_theme_accent": {
"type": "string"
}
}
},
"AuthCredentials": {
"type": "object",
"properties": {
"username": {
"type": "string"
},
"password": {
"type": "string"
}
}
},
"AuthOutput": {
"type": "object",
"properties": {
"admin": {
"type": "boolean"
}
}
},
"CollectionFile": {
"oneOf": [
{
"$ref": "#/components/schemas/CollectionFileDirectory"
},
{
"$ref": "#/components/schemas/CollectionFileSong"
}
]
},
"CollectionFileDirectory": {
"type": "object",
"properties": {
"Directory": {
"$ref": "#/components/schemas/Directory"
}
}
},
"CollectionFileSong": {
"type": "object",
"properties": {
"Song": {
"$ref": "#/components/schemas/Song"
}
}
},
"Directory": {
"type": "object",
"properties": {
"path": {
"type": "string",
"example": "My Music/Metal/Stratovarius/Destiny",
"required": true
},
"artist": {
"type": "string",
"example": "Stratovarius"
},
"year": {
"type": "integer",
"example": 1998
},
"album": {
"type": "string",
"example": "Destiny"
},
"artwork": {
"type": "string",
"example": "My Music/Metal/Stratovarius/Destiny/Folder.png"
},
"date_added": {
"type": "integer",
"example": 1453179635,
"required": true
}
}
},
"Song": {
"type": "object",
"properties": {
"path": {
"type": "string",
"example": "My Music/Metal/Stratovarius/Destiny/Anthem of the World.mp3",
"required": true
},
"track_number": {
"type": "integer",
"example": 9
},
"disc_number": {
"type": "integer",
"example": 1
},
"title": {
"type": "string",
"example": "Anthem of the World"
},
"artist": {
"type": "string",
"example": "Stratovarius"
},
"album_artist": {
"type": "string",
"example": null
},
"year": {
"type": "integer",
"example": 1998
},
"album": {
"type": "string",
"example": "Destiny"
},
"artwork": {
"type": "string",
"example": "My Music/Metal/Stratovarius/Destiny/Folder.png"
},
"duration": {
"type": "integer",
"example": 571
}
}
},
"ListPlaylistsEntry": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "Friday Chill"
}
}
},
"SavePlaylistInput": {
"type": "object",
"properties": {
"tracks": {
"type": "array",
"items": {
"type": "string",
"example": "My Music/Metal/Stratovarius/Destiny/Anthem of the World.mp3"
}
}
}
}
},
"securitySchemes": {
"auth_http_header": {
"type": "http",
"scheme": "basic"
},
"auth_cookie": {
"type": "apikey",
"in": "cookie",
"name": "session",
"description": "A session token obtained returned as a server cookie by making a request via the auth_http_header scheme."
},
"admin_http_header": {
"type": "http",
"scheme": "basic",
"description": "Identical to the auth_http_header scheme but only for users recognized as admin by the Polaris server"
},
"admin_cookie": {
"type": "apikey",
"in": "cookie",
"name": "session",
"description": "Identical to the auth_cookie scheme but only for users recognized as admin by the Polaris server"
}
},
"links": {},
"callbacks": {}
},
"security": []
}