392 lines
10 KiB
YAML
392 lines
10 KiB
YAML
swagger: "2.0"
|
|
info:
|
|
version: "0.5.0"
|
|
title: AzuraCast
|
|
description: '
|
|
AzuraCast is a standalone, turnkey web radio management tool. Radio stations hosted by AzuraCast expose a public API for viewing now playing data, making requests and more.
|
|
|
|
### Authenticating
|
|
|
|
Some request types require an API key, either to perform administrative steps or avoid public rate-limiting. API keys can be generated from the AzuraCast global administration panel. When making an authenticated request, any of the following methods can be used to supply the key:
|
|
|
|
* The "X-API-Key" HTTP header supplied in the request
|
|
|
|
* The "key" parameter supplied via GET or POST (?key=a1b2c3...)
|
|
|
|
|
|
### Important Notes
|
|
|
|
* Many API calls are cached for performance reasons, and some implement rate-limits to prevent flooding the system. Typically, calls authenticated with an API key have rate limits removed.
|
|
|
|
* API signatures may change between software versions. Check the GitHub repository for more information when updating.
|
|
|
|
* All timestamps in API calls are supplied as UNIX timestamps, i.e. seconds from 1/1/1970.
|
|
|
|
|
|
### Station "Short Codes"
|
|
|
|
In lieu of a station ID, some station-related API calls allow for what is called a "shortcode". This is the name of the station, in lower case, with its special characters removed. For example, "My Awesome Radio!" would become "my_awesome_radio".
|
|
|
|
### Song Identifiers
|
|
|
|
Most database entries have an auto-incrementing unique identifier, but songs use a hash-based identification system that avoids collisions based on spacing or punctuation differences.'
|
|
license:
|
|
name: Apache 2.0
|
|
url: https://github.com/AzuraCast/AzuraCast/blob/master/License.txt
|
|
host: localhost:8080
|
|
basePath: /api
|
|
schemes:
|
|
- http
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
paths:
|
|
/nowplaying:
|
|
get:
|
|
description: Returns all now playing data for active stations.
|
|
tags:
|
|
- Now Playing
|
|
operationId: Nowplaying
|
|
produces:
|
|
- application/json
|
|
parameters: []
|
|
responses:
|
|
200:
|
|
description: "Now Playing Songs"
|
|
schema:
|
|
$ref: '#/definitions/NowplayingResponse'
|
|
x-operation-settings:
|
|
CollectParameters: false
|
|
AllowDynamicQueryParameters: false
|
|
AllowDynamicFormParameters: false
|
|
IsMultiContentStreaming: false
|
|
/nowplaying/{id}:
|
|
get:
|
|
description: >-
|
|
**Station Specified by Numeric ID**
|
|
|
|
Returns a single station's now-playing information based on a station identifier.
|
|
tags:
|
|
- Now Playing
|
|
operationId: NowplayingById
|
|
produces:
|
|
- application/json
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
type: number
|
|
format: double
|
|
description: The station ID.
|
|
responses:
|
|
200:
|
|
description: "The now playing information for the specified station."
|
|
schema:
|
|
$ref: '#/definitions/NowplayingbyidResponse'
|
|
400:
|
|
description: >-
|
|
Returned if an invalid station ID is specified.
|
|
|
|
|
|
+Body
|
|
|
|
|
|
{
|
|
status: "error",
|
|
error: "Station not found."
|
|
}
|
|
schema: {}
|
|
x-unitTests: []
|
|
x-operation-settings:
|
|
CollectParameters: false
|
|
AllowDynamicQueryParameters: false
|
|
AllowDynamicFormParameters: false
|
|
IsMultiContentStreaming: false
|
|
/stations:
|
|
get:
|
|
description: List all stations from all categories.
|
|
tags:
|
|
- Stations
|
|
operationId: Stations
|
|
produces:
|
|
- application/json
|
|
parameters: []
|
|
responses:
|
|
200:
|
|
description: "List of all stations."
|
|
schema:
|
|
$ref: '#/definitions/StationsResponse'
|
|
x-operation-settings:
|
|
CollectParameters: false
|
|
AllowDynamicQueryParameters: false
|
|
AllowDynamicFormParameters: false
|
|
IsMultiContentStreaming: false
|
|
/station/{id}:
|
|
get:
|
|
description: Station info for the specified numeric identifier.
|
|
tags:
|
|
- Stations
|
|
operationId: StationsById
|
|
produces:
|
|
- application/json
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
type: number
|
|
format: double
|
|
description: The station ID.
|
|
responses:
|
|
200:
|
|
description: "List of stations by ID."
|
|
schema:
|
|
$ref: '#/definitions/StationsbyidResponse'
|
|
400:
|
|
description: >-
|
|
Returned if an invalid station ID is specified.
|
|
|
|
|
|
+Body
|
|
|
|
|
|
{
|
|
status: "error",
|
|
error: "Station not found."
|
|
}
|
|
schema: {}
|
|
x-operation-settings:
|
|
CollectParameters: false
|
|
AllowDynamicQueryParameters: false
|
|
AllowDynamicFormParameters: false
|
|
IsMultiContentStreaming: false
|
|
/station/{station}/requests:
|
|
get:
|
|
description: Get all currently requestable songs from the specified station.
|
|
tags:
|
|
- Song Requests
|
|
operationId: RequestsListByStationId
|
|
produces:
|
|
- application/json
|
|
parameters:
|
|
- name: station
|
|
in: path
|
|
required: true
|
|
type: number
|
|
format: double
|
|
description: The station ID.
|
|
responses:
|
|
200:
|
|
description: "A list of all requestable songs on the station."
|
|
schema:
|
|
$ref: '#/definitions/RequestslistbystationidResponse'
|
|
400:
|
|
description: >-
|
|
Returned if an invalid station ID is specified.
|
|
|
|
+Body
|
|
{
|
|
status: "error",
|
|
error: "Station not found."
|
|
}
|
|
schema: {}
|
|
x-unitTests: []
|
|
x-operation-settings:
|
|
CollectParameters: false
|
|
AllowDynamicQueryParameters: false
|
|
AllowDynamicFormParameters: false
|
|
IsMultiContentStreaming: false
|
|
/station/{station}/request/{song_id}:
|
|
post:
|
|
description: Submit a request for a station to play a song with the specified ID.
|
|
tags:
|
|
- Song Requests
|
|
operationId: RequestsSubmitByStationIdAndSongId
|
|
produces:
|
|
- application/json
|
|
parameters:
|
|
- name: station
|
|
in: path
|
|
required: true
|
|
type: number
|
|
format: double
|
|
description: The station ID.
|
|
- name: song_id
|
|
in: path
|
|
required: true
|
|
type: string
|
|
responses:
|
|
200:
|
|
description: "Successful request."
|
|
schema:
|
|
$ref: '#/definitions/RequestssubmitbystationidandsongidResponse'
|
|
400:
|
|
description: >-
|
|
Returned if any of the following circumstances occur:
|
|
|
|
* Invalid station ID specified
|
|
|
|
* Invalid song ID specified
|
|
|
|
* Song requests disabled by station
|
|
|
|
* Song played too recently on the station
|
|
schema: {}
|
|
x-unitTests: []
|
|
x-operation-settings:
|
|
CollectParameters: false
|
|
AllowDynamicQueryParameters: false
|
|
AllowDynamicFormParameters: false
|
|
IsMultiContentStreaming: false
|
|
/:
|
|
get:
|
|
description: The homepage of the API, that provides a basic ping function and a link to this documentation.
|
|
tags:
|
|
- Utilities
|
|
operationId: Unnammed Endpoint
|
|
produces:
|
|
- application/json
|
|
parameters: []
|
|
responses:
|
|
200:
|
|
description: "Heartbeat status."
|
|
schema:
|
|
$ref: '#/definitions/UnnammedEndpointResponse'
|
|
x-operation-settings:
|
|
CollectParameters: false
|
|
AllowDynamicQueryParameters: false
|
|
AllowDynamicFormParameters: false
|
|
IsMultiContentStreaming: false
|
|
/status:
|
|
get:
|
|
description: A basic ping function that returns the current UNIX timestamp (for caching tests).
|
|
tags:
|
|
- Utilities
|
|
operationId: Status
|
|
produces:
|
|
- application/json
|
|
parameters: []
|
|
responses:
|
|
200:
|
|
description: "Pong"
|
|
schema:
|
|
type: string
|
|
x-operation-settings:
|
|
CollectParameters: false
|
|
AllowDynamicQueryParameters: false
|
|
AllowDynamicFormParameters: false
|
|
IsMultiContentStreaming: false
|
|
/time:
|
|
get:
|
|
description: Return the server's timezone configuration, as well as several formats of the current UTC and localized timestamp.
|
|
tags:
|
|
- Utilities
|
|
operationId: Time
|
|
produces:
|
|
- application/json
|
|
parameters: []
|
|
responses:
|
|
200:
|
|
description: "The system time."
|
|
schema:
|
|
$ref: '#/definitions/TimeResponse'
|
|
x-operation-settings:
|
|
CollectParameters: false
|
|
AllowDynamicQueryParameters: false
|
|
AllowDynamicFormParameters: false
|
|
IsMultiContentStreaming: false
|
|
definitions:
|
|
NowplayingResponse:
|
|
title: Nowplaying Response
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
result:
|
|
type: array
|
|
items:
|
|
type: string
|
|
required:
|
|
- status
|
|
- result
|
|
NowplayingbyidResponse:
|
|
title: NowplayingById Response
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
result:
|
|
type: string
|
|
required:
|
|
- status
|
|
- result
|
|
StationsResponse:
|
|
title: Stations Response
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
result:
|
|
type: array
|
|
items:
|
|
type: string
|
|
required:
|
|
- status
|
|
- result
|
|
StationsbyidResponse:
|
|
title: StationsById Response
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
result:
|
|
type: string
|
|
required:
|
|
- status
|
|
- result
|
|
RequestslistbystationidResponse:
|
|
title: RequestsListByStationId Response
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
result:
|
|
type: array
|
|
items:
|
|
type: string
|
|
required:
|
|
- status
|
|
- result
|
|
RequestssubmitbystationidandsongidResponse:
|
|
title: RequestsSubmitByStationIdAndSongId Response
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
result:
|
|
type: string
|
|
required:
|
|
- status
|
|
- result
|
|
UnnammedEndpointResponse:
|
|
title: Unnammed Endpoint Response
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
result:
|
|
type: string
|
|
required:
|
|
- status
|
|
- result
|
|
TimeResponse:
|
|
title: Time Response
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
result:
|
|
type: string
|
|
required:
|
|
- status
|
|
- result |