Inital OpenAPIv3 Spec (#223)
This commit is contained in:
John Hobbs
GitHub
parent
27a4c8c895
commit
31c5f8241c
513
openapi.yaml
Normal file
513
openapi.yaml
Normal file
@ -0,0 +1,513 @@
|
||||
openapi: 3.0.1
|
||||
info:
|
||||
title: Owncast
|
||||
description: Owncast is a self-hosted live video and web chat server for use with existing popular broadcasting software.
|
||||
version: '0.0.2'
|
||||
servers: []
|
||||
|
||||
tags:
|
||||
- name: Admin
|
||||
description: Admin operations requiring authentication.
|
||||
- name: Chat
|
||||
description: Endpoints related to the chat interface.
|
||||
|
||||
components:
|
||||
schemas:
|
||||
BasicResponse:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
message:
|
||||
type: string
|
||||
InstanceDetails:
|
||||
type: object
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
title:
|
||||
type: string
|
||||
summary:
|
||||
type: string
|
||||
description: This is brief summary of whom you are or what the stream is.
|
||||
logo:
|
||||
type: object
|
||||
properties:
|
||||
large:
|
||||
type: string
|
||||
small:
|
||||
type: string
|
||||
tags:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
socialHandles:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
platform:
|
||||
type: string
|
||||
example: github
|
||||
url:
|
||||
type: string
|
||||
example: http://github.com/owncast/owncast
|
||||
extraUserInfoFileName:
|
||||
type: string
|
||||
description: Path to additional content about the server.
|
||||
version:
|
||||
type: string
|
||||
example: Owncast v0.0.2-macOS (ef3796a033b32a312ebf5b334851cbf9959e7ecb)
|
||||
S3:
|
||||
type: object
|
||||
properties:
|
||||
enabled:
|
||||
type: boolean
|
||||
endpoint:
|
||||
type: string
|
||||
servingEndpoint:
|
||||
type: string
|
||||
accessKey:
|
||||
type: string
|
||||
secret:
|
||||
type: string
|
||||
bucket:
|
||||
type: string
|
||||
region:
|
||||
type: string
|
||||
acl:
|
||||
type: string
|
||||
required:
|
||||
- enabled
|
||||
StreamQuality:
|
||||
type: object
|
||||
properties:
|
||||
videoPassthrough:
|
||||
type: boolean
|
||||
audioPassthrough:
|
||||
type: boolean
|
||||
videoBitrate:
|
||||
type: integer
|
||||
audioBitrate:
|
||||
type: integer
|
||||
scaledWidth:
|
||||
type: integer
|
||||
scaledHeight:
|
||||
type: integer
|
||||
framerate:
|
||||
type: integer
|
||||
encoderPreset:
|
||||
type: string
|
||||
TimestampedValue:
|
||||
type: object
|
||||
properties:
|
||||
time:
|
||||
type: string
|
||||
format: date-time
|
||||
value:
|
||||
type: integer
|
||||
|
||||
|
||||
securitySchemes:
|
||||
AdminBasicAuth:
|
||||
type: http
|
||||
scheme: basic
|
||||
description: The username for admin basic auth is `admin` and the password is the stream key.
|
||||
|
||||
responses:
|
||||
BasicResponse:
|
||||
description: Operation Success/Failure Response
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/BasicResponse"
|
||||
examples:
|
||||
success:
|
||||
summary: Operation succeeded.
|
||||
value: {"success": true, "message": "inbound stream disconnected"}
|
||||
failure:
|
||||
summary: Operation failed.
|
||||
value: {"success": false, "message": "no inbound stream connected"}
|
||||
|
||||
paths:
|
||||
|
||||
/api/config:
|
||||
get:
|
||||
summary: Information
|
||||
description: Get the public information about the server. Adds context to the server, as well as information useful for the user interface.
|
||||
tags: ["Server"]
|
||||
responses:
|
||||
'200':
|
||||
description: ""
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/InstanceDetails"
|
||||
|
||||
/api/status:
|
||||
get:
|
||||
summary: Current Status
|
||||
description: This endpoint is used to discover when a server is broadcasting, the number of active viewers as well as other useful information for updating the user interface.
|
||||
tags: ["Server"]
|
||||
responses:
|
||||
'200':
|
||||
description: ""
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
lastConnectTime:
|
||||
type: string
|
||||
nullable: true
|
||||
format: date-time
|
||||
overallMaxViewerCount:
|
||||
type: integer
|
||||
sessionMaxViewerCount:
|
||||
type: integer
|
||||
online:
|
||||
type: boolean
|
||||
viewerCount:
|
||||
type: integer
|
||||
lastDisconnectTime:
|
||||
type: string
|
||||
nullable: true
|
||||
format: date-time
|
||||
examples:
|
||||
online:
|
||||
value:
|
||||
lastConnectTime: "2020-10-03T21:36:22-05:00"
|
||||
lastDisconnectTime: null
|
||||
online: true
|
||||
overallMaxViewerCount: 420
|
||||
sessionMaxViewerCount: 12
|
||||
viewerCount: 7
|
||||
|
||||
/api/chat:
|
||||
get:
|
||||
summary: Historical Chat Messages
|
||||
description: Used to get all chat messages prior to connecting to the websocket.
|
||||
tags: ["Chat"]
|
||||
responses:
|
||||
'200':
|
||||
description: ""
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
author:
|
||||
type: string
|
||||
description: Username of the chat message poster.
|
||||
body:
|
||||
type: string
|
||||
description: Escaped HTML of the chat message content.
|
||||
image:
|
||||
type: string
|
||||
description: URL of the chat user avatar.
|
||||
id:
|
||||
type: string
|
||||
description: Unique ID of the chat message.
|
||||
visible:
|
||||
type: boolean
|
||||
description: "TODO"
|
||||
timestamp:
|
||||
type: string
|
||||
format: date-time
|
||||
|
||||
/api/yp:
|
||||
get:
|
||||
summary: Yellow Pages Information
|
||||
description: Information to be used in the Yellow Pages service, a global directory of Owncast servers.
|
||||
tags: ["Server"]
|
||||
responses:
|
||||
'200':
|
||||
description: ""
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
description:
|
||||
type: string
|
||||
logo:
|
||||
type: string
|
||||
nsfw:
|
||||
type: boolean
|
||||
tags:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
online:
|
||||
type: boolean
|
||||
viewerCount:
|
||||
type: integer
|
||||
overallMaxViewerCount:
|
||||
type: integer
|
||||
sessionMaxViewerCount:
|
||||
type: integer
|
||||
lastConnectTime:
|
||||
type: string
|
||||
nullable: true
|
||||
format: date-time
|
||||
|
||||
/api/emoji:
|
||||
get:
|
||||
summary: Get Custom Emoji
|
||||
description: Get a list of custom emoji that are supported in chat.
|
||||
tags: ["Chat"]
|
||||
responses:
|
||||
'200':
|
||||
description: ""
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
description: The name of the Emoji
|
||||
emoji:
|
||||
type: string
|
||||
description: The relative path to the Emoji image file
|
||||
examples:
|
||||
default:
|
||||
value:
|
||||
items:
|
||||
- name: nicolas_cage_party
|
||||
emoji: /img/emoji/nicolas_cage_party.gif
|
||||
- name: parrot
|
||||
emoji: /img/emoji/parrot.gif
|
||||
|
||||
/api/admin/broadcaster:
|
||||
get:
|
||||
summary: "Broadcaster Details"
|
||||
tags: ["Admin"]
|
||||
security:
|
||||
- AdminBasicAuth: []
|
||||
responses:
|
||||
'200':
|
||||
description: Connected Broadcaster Details
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
message:
|
||||
type: string
|
||||
broadcaster:
|
||||
type: object
|
||||
properties:
|
||||
remoteAddr:
|
||||
type: string
|
||||
time:
|
||||
type: string
|
||||
format: date-time
|
||||
streamDetails:
|
||||
type: object
|
||||
properties:
|
||||
width:
|
||||
type: integer
|
||||
height:
|
||||
type: integer
|
||||
frameRate:
|
||||
type: integer
|
||||
videoBitrate:
|
||||
type: integer
|
||||
videoCodec:
|
||||
type: string
|
||||
audioBitrate:
|
||||
type: integer
|
||||
audioCodec:
|
||||
type: string
|
||||
encoder:
|
||||
type: string
|
||||
examples:
|
||||
connected:
|
||||
summary: "Broadcaster Connected"
|
||||
value:
|
||||
success: true
|
||||
message: ""
|
||||
broadcaster:
|
||||
remoteAddr: 127.0.0.1
|
||||
time: "TODO"
|
||||
streamDetails:
|
||||
width: 640
|
||||
height: 480
|
||||
frameRate: 24
|
||||
videoBitrate: 1500
|
||||
videoCodec: "todo"
|
||||
audioBitrate: 256
|
||||
audioCodec: "aac"
|
||||
encoder: "todo"
|
||||
not-connected:
|
||||
summary: "Broadcaster Not Connected"
|
||||
value:
|
||||
success: false
|
||||
message: "no broadcaster connected"
|
||||
|
||||
/api/admin/disconnect:
|
||||
post:
|
||||
summary: Disconnect Broadcaster
|
||||
description: Disconnect the active inbound stream, if one exists, and terminate the broadcast.
|
||||
tags: ["Admin"]
|
||||
security:
|
||||
- AdminBasicAuth: []
|
||||
responses:
|
||||
'200':
|
||||
$ref: "#/components/responses/BasicResponse"
|
||||
|
||||
|
||||
/api/admin/changekey:
|
||||
post:
|
||||
summary: Update Stream Key
|
||||
description: Change the stream key in memory, but not in the config file. This will require all broadcasters to be reconfigured to connect again.
|
||||
tags: ["Admin"]
|
||||
security:
|
||||
- AdminBasicAuth: []
|
||||
requestBody:
|
||||
description: ""
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
key:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Stream was disconnected.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
example: true
|
||||
message:
|
||||
type: string
|
||||
example: changed
|
||||
|
||||
/api/admin/serverconfig:
|
||||
get:
|
||||
summary: Server Configuration
|
||||
description: Get the current configuration of the Owncast server.
|
||||
tags: ["Admin"]
|
||||
security:
|
||||
- AdminBasicAuth: []
|
||||
responses:
|
||||
'200':
|
||||
description: ""
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
instanceDetails:
|
||||
$ref: "#/components/schemas/InstanceDetails"
|
||||
ffmpegPath:
|
||||
type: string
|
||||
webServerPort:
|
||||
type: integer
|
||||
s3:
|
||||
$ref: "#/components/schemas/S3"
|
||||
videoSettings:
|
||||
type: object
|
||||
properties:
|
||||
videoQualityVariants:
|
||||
type: array
|
||||
items:
|
||||
$ref: "#/components/schemas/StreamQuality"
|
||||
segmentLengthSeconds:
|
||||
type: integer
|
||||
numberOfPlaylistItems:
|
||||
type: integer
|
||||
|
||||
/api/admin/viewersOverTime:
|
||||
get:
|
||||
summary: Viewers Over Time
|
||||
description: Get the tracked viewer count over the collected period.
|
||||
tags: ["Admin"]
|
||||
security:
|
||||
- AdminBasicAuth: []
|
||||
responses:
|
||||
'200':
|
||||
description: ""
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
$ref: "#/components/schemas/TimestampedValue"
|
||||
examples:
|
||||
default:
|
||||
value:
|
||||
- time: "2020-10-03T21:41:00.381996-05:00"
|
||||
value: 50
|
||||
- time: "2020-10-03T21:42:00.381996-05:00"
|
||||
value: 52
|
||||
|
||||
|
||||
|
||||
|
||||
/api/admin/hardwarestats:
|
||||
get:
|
||||
summary: Hardware Stats
|
||||
description: "Get the CPU, Memory and Disk utilization levels over the collected period."
|
||||
tags: ["Admin"]
|
||||
security:
|
||||
- AdminBasicAuth: []
|
||||
responses:
|
||||
'200':
|
||||
description: ""
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
cpu:
|
||||
type: array
|
||||
items:
|
||||
$ref: "#/components/schemas/TimestampedValue"
|
||||
memory:
|
||||
type: array
|
||||
items:
|
||||
$ref: "#/components/schemas/TimestampedValue"
|
||||
disk:
|
||||
type: array
|
||||
items:
|
||||
$ref: "#/components/schemas/TimestampedValue"
|
||||
examples:
|
||||
default:
|
||||
value:
|
||||
cpu:
|
||||
- time: "2020-10-03T21:41:00.381996-05:00"
|
||||
value: 23
|
||||
- time: "2020-10-03T21:42:00.381996-05:00"
|
||||
value: 27
|
||||
- time: "2020-10-03T21:43:00.381996-05:00"
|
||||
value: 22
|
||||
memory:
|
||||
- time: "2020-10-03T21:41:00.381996-05:00"
|
||||
value: 65
|
||||
- time: "2020-10-03T21:42:00.381996-05:00"
|
||||
value: 66
|
||||
- time: "2020-10-03T21:43:00.381996-05:00"
|
||||
value: 72
|
||||
disk:
|
||||
- time: "2020-10-03T21:41:00.381996-05:00"
|
||||
value: 11
|
||||
- time: "2020-10-03T21:42:00.381996-05:00"
|
||||
value: 11
|
||||
- time: "2020-10-03T21:43:00.381996-05:00"
|
||||
value: 11
|
||||
Loading…
Reference in New Issue
Block a user