# SPDX-License-Identifier: GPL-3.0-or-later # # copyright (c) 2020 Thomas Ruschival # Licensed under GNU PUBLIC LICENSE Version 3 or later openapi: 3.0.0 info: description: Open API for Digital Rooster version: '1.0' title: DigitalRooster license: name: GPLv3 servers: - url: '{server}/api/1.0/' variables: server: default: http://digitalrooster:6666 ############################################################################### components: # HTTP responses in case of errors responses: Success: description: Request processed with success! SuccessCreated: description: Resource created with success! content: application/json: schema: $ref: '#/components/schemas/ResourceUuid' InvalidRequest: description: Invalid request parameters! content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The specified resource was not found content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' # Objects # schemas: # Schema for error response body Error: type: object properties: code: type: string message: type: string required: - code - message # UUid of created resource ResourceUuid: type: object properties: id: type: string description: 'Uuid of created resource' required: - id # Station definition Station: required: - name - url properties: id: type: string name: type: string url: type: string # Array of Stations Stations: type: array items: $ref: '#/components/schemas/Station' # PodcastSource definition Podcast: required: - title - url properties: id: type: string title: type: string url: type: string updateInterval: type: integer maxEpisodes: type: integer # Array of PodcastSources Podcasts: type: array items: $ref: '#/components/schemas/Podcast' # Alarm definition Alarm: required: - time - period - url - enabled properties: time: type: string period: type: string enum: - once - daily - workdays - weekend url: type: string enabled: type: boolean volume: type: integer id: type: string # Alarm array Alarms: type: array items: $ref: '#/components/schemas/Alarm' # parameters for functions ######################################### parameters: ArrayLength: name: length in: query description: number of items if omitted or invalid all remaining elements will be assumed required: false schema: type: integer ArrayOffset: name: offset in: query description: offset from start of list if omitted or invalid 0 will be assumed required: false schema: type: integer id: name: id in: path description: unique id to identify item required: true schema: type: string ############################################################################### # Paths as API Endpoints ############################################################################### paths: # Internet Radio Streams /radios: get: # Get All Streams operationId: iradio.read_all tags: - Radios summary: Read all Internet radio streams description: returns a list of Internet radio streams parameters: - $ref: '#/components/parameters/ArrayLength' - $ref: '#/components/parameters/ArrayOffset' responses: '200': description: Successfully read stream list content: application/json: schema: $ref: '#/components/schemas/Stations' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' post: # Create a stream operationId: iradio.create tags: - Radios summary: Create a station info and add it to the list requestBody: description: Internet radio station to create required: true content: application/json: schema: $ref: '#/components/schemas/Station' responses: '200': $ref: '#/components/responses/SuccessCreated' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/InvalidRequest' '404': $ref: '#/components/responses/NotFound' # Manipulate single Radios Stream /radios/{id}: get: # read single stream by id operationId: iradio.read_one tags: - Radios summary: Read one Internet radio station parameters: - $ref: '#/components/parameters/id' responses: '200': description: Successfully read a single radio station content: application/json: schema: $ref: '#/components/schemas/Station' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/InvalidRequest' '404': $ref: '#/components/responses/NotFound' delete: # delete stream identified by id operationId: iradio.delete tags: - Radios summary: Delete Internet radio station from list parameters: - $ref: '#/components/parameters/id' responses: '200': $ref: '#/components/responses/Success' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' ############################################################################### # Podcast Sources /podcasts: get: # Get all podcasts operationId: podcasts.read_all tags: - Podcasts summary: Read all podcast rss sources parameters: - $ref: '#/components/parameters/ArrayLength' - $ref: '#/components/parameters/ArrayOffset' responses: '200': description: successfully read list content: application/json: schema: $ref: '#/components/schemas/Podcasts' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/InvalidRequest' '404': $ref: '#/components/responses/NotFound' post: # Add a podcast source with RSS feed operationId: podcasts.create tags: - Podcasts summary: Add a podcast source with RSS feed and add it to the list requestBody: description: Podcast source to create required: true content: application/json: schema: $ref: '#/components/schemas/Podcast' responses: '200': $ref: '#/components/responses/SuccessCreated' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/InvalidRequest' /podcasts/{id}: get: # read single podcast by id operationId: podcasts.read_one tags: - Podcasts summary: Read one Podcast identified by id parameters: - $ref: '#/components/parameters/id' responses: '200': description: Successfully read Podcast content: application/json: schema: $ref: '#/components/schemas/Podcast' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/InvalidRequest' '404': $ref: '#/components/responses/NotFound' delete: # delete podcasts identified by id operationId: podcasts.delete tags: - Podcasts summary: Delete Podcast from list parameters: - $ref: '#/components/parameters/id' responses: '200': $ref: '#/components/responses/Success' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/InvalidRequest' '404': $ref: '#/components/responses/NotFound' ################################################################################ # Alarms /alarms: get: # Get all Alarms operationId: alarms.read_all tags: - Alarms summary: Read all Alarms parameters: - $ref: '#/components/parameters/ArrayLength' - $ref: '#/components/parameters/ArrayOffset' responses: '200': description: Successfully read alarm list content: application/json: schema: $ref: '#/components/schemas/Alarms' '404': description: Wrong length/offset post: # Create new alarm operationId: alarms.create tags: - Alarms summary: Create a new alarm entry and add it to the list requestBody: description: Alarm object to create required: true content: application/json: schema: $ref: '#/components/schemas/Alarm' responses: '200': $ref: '#/components/responses/SuccessCreated' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/InvalidRequest' '404': $ref: '#/components/responses/NotFound' /alarms/{id}: get: # read single alarm by id operationId: alarms.read_one tags: - Alarms summary: Read one Alarm parameters: - $ref: '#/components/parameters/id' responses: '200': description: Successfully read Alarm content: application/json: schema: $ref: '#/components/schemas/Alarm' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/InvalidRequest' '404': $ref: '#/components/responses/NotFound' delete: # delete alarm identified by id operationId: alarms.delete tags: - Alarms summary: Delete alarm from list parameters: - $ref: '#/components/parameters/id' responses: '200': $ref: '#/components/responses/Success' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/InvalidRequest' '404': $ref: '#/components/responses/NotFound'