Skip to content

Commit 3351413

Browse files
stv0gstv0g
committed
add first draft of OpenAPI spec
1 parent 87c2dcb commit 3351413

File tree

1 file changed

+324
-0
lines changed

1 file changed

+324
-0
lines changed

‎doc/openapi.yaml

Lines changed: 324 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,324 @@
1+
---
2+
openapi: 3.0.0
3+
info:
4+
title: VILLAScontroller API
5+
description: 'A HTTP/REST API for controlling VILLAScontroller remotely for querying component status as well as issuing control actions.'
6+
version: 0.0.1
7+
license:
8+
name: Apache-2.0
9+
url: https://www.apache.org/licenses/LICENSE-2.0
10+
servers:
11+
- url: https://villas.k8s.eonerc.rwth-aachen.de/api/v1
12+
description: Demo instance at RWTH Aachen
13+
paths:
14+
/:
15+
get:
16+
summary: 'Get status of VILLAScontroller daemon'
17+
operationId: getStatus
18+
responses:
19+
'200':
20+
description: ''
21+
content:
22+
application/json:
23+
schema:
24+
type: object
25+
properties:
26+
components:
27+
type: array
28+
items:
29+
type: string
30+
format: uuid
31+
status:
32+
type: object
33+
properties:
34+
version:
35+
type: string
36+
uptime:
37+
type: number
38+
host:
39+
type: string
40+
kernel:
41+
type: object
42+
properties:
43+
sysname:
44+
type: string
45+
nodename:
46+
type: string
47+
release:
48+
type: string
49+
version:
50+
type: string
51+
machine:
52+
type: string
53+
54+
example:
55+
components:
56+
- f4751894-205e-11eb-aefb-0741ff98abca
57+
- 3ddd318e-fee1-46d7-bff4-7c064d640d4e
58+
status:
59+
version: 0.3.2
60+
uptime: 15.38102650642395
61+
host: lat.0l.de
62+
kernel:
63+
sysname: Linux
64+
nodename: lat.0l.de
65+
release: 5.13.14-200.fc34.x86_64
66+
version: '#1 SMP Fri Sep 3 15:33:01 UTC 2021'
67+
machine: x86_64
68+
69+
70+
/component/{uuid}:
71+
get:
72+
parameters:
73+
- name: uuid
74+
in: path
75+
required: true
76+
schema:
77+
type: string
78+
format: uuid
79+
80+
operationId: getComponentStatus
81+
summary: 'Get the current status of a component'
82+
responses:
83+
200:
84+
description: ''
85+
content:
86+
application/json:
87+
schema:
88+
type: object
89+
properties:
90+
components:
91+
type: array
92+
items:
93+
type: string
94+
format: uuid
95+
96+
status:
97+
type: object
98+
properties:
99+
managed_by:
100+
type: string
101+
format: uuid
102+
103+
state:
104+
type: string
105+
enum:
106+
- idle
107+
- starting
108+
- running
109+
- stopping
110+
- pausing
111+
- paused
112+
- resuming
113+
- error
114+
- resetting
115+
- shuttingdown
116+
- shutdown
117+
- gone
118+
119+
version:
120+
type: string
121+
uptime:
122+
type: number
123+
host:
124+
type: string
125+
kernel:
126+
type: object
127+
properties:
128+
sysname:
129+
type: string
130+
nodename:
131+
type: string
132+
release:
133+
type: string
134+
version:
135+
type: string
136+
machine:
137+
type: string
138+
139+
properties:
140+
type: object
141+
properties:
142+
category:
143+
type: string
144+
enum:
145+
- manager
146+
- simulator
147+
- gateway
148+
type:
149+
type: string
150+
pattern: '[a-z-]+'
151+
name:
152+
type: string
153+
realm:
154+
type: string
155+
pattern: '[a-z0-9-.]+'
156+
uuid:
157+
type: string
158+
format: uuid
159+
160+
additionalProperties: true
161+
162+
schema:
163+
type: object
164+
additionalProperties:
165+
$ref: 'https://json-schema.org/draft/2020-12/schema'
166+
167+
example:
168+
components: []
169+
status:
170+
state: idle
171+
version: 0.3.2
172+
uptime: 480.25064611434937
173+
host: lat.0l.de
174+
kernel:
175+
sysname: Linux
176+
nodename: lat.0l.de
177+
release: 5.13.14-200.fc34.x86_64
178+
version: '#1 SMP Fri Sep 3 15:33:01 UTC 2021'
179+
machine: x86_64
180+
managed_by: f4751894-205e-11eb-aefb-0741ff98abca
181+
properties:
182+
category: manager
183+
type: generic
184+
name: Standard Controller
185+
realm: de.rwth-aachen.eonerc.acs
186+
uuid: f4751894-205e-11eb-aefb-0741ff98abca
187+
schema:
188+
create:
189+
$schema: 'http://json-schema.org/draft-07/schema'
190+
$id: 'http://example.com/example.json'
191+
type: object
192+
default: {}
193+
required:
194+
- name
195+
- category
196+
- location
197+
- owner
198+
- realm
199+
- type
200+
- api_url
201+
- ws_url
202+
properties:
203+
name:
204+
$id: '#/properties/name'
205+
type: string
206+
title: Component name
207+
default: New Component
208+
examples:
209+
- 'Generic Simulator #1'
210+
owner:
211+
$id: '#/properties/owner'
212+
type: string
213+
title: Component owner
214+
default: ''
215+
examples:
216+
- rmr
217+
- svg
218+
realm:
219+
$id: '#/properties/realm'
220+
type: string
221+
title: Component realm
222+
default: ''
223+
examples:
224+
- de.rwth-aachen.eonerc.acs
225+
category:
226+
$id: '#/properties/category'
227+
type: string
228+
title: Component category
229+
default: ''
230+
examples:
231+
- simulator
232+
location:
233+
$id: '#/properties/location'
234+
type: string
235+
title: Component location
236+
default: ''
237+
examples:
238+
- Richard's PC
239+
type:
240+
$id: '#/properties/type'
241+
type: string
242+
title: The type schema
243+
default: ''
244+
examples:
245+
- generic
246+
uuid:
247+
$id: '#/properties/uuid'
248+
type: 'null'
249+
title: The uuid schema
250+
default: null
251+
ws_url:
252+
$id: '#/properties/ws_url'
253+
type: string
254+
title: The ws_url schema
255+
default: ''
256+
examples:
257+
- 'https://villas.k8s.eonerc.rwth-aachen.de/ws/relay/generic_1'
258+
api_url:
259+
$id: '#/properties/api_url'
260+
type: string
261+
title: The api_url schema
262+
default: ''
263+
examples:
264+
- 'https://villas.k8s.eonerc.rwth-aachen.de/api/ic/generic_1'
265+
shell:
266+
$id: '#/properties/shell'
267+
type: boolean
268+
title: The shell schema
269+
default: false
270+
examples:
271+
- true
272+
whitelist:
273+
$id: '#/properties/whitelist'
274+
type: array
275+
title: The whitelist schema
276+
default: []
277+
examples:
278+
- - /sbin/ping
279+
- ^echo
280+
additionalItems: true
281+
items:
282+
$id: '#/properties/whitelist/items'
283+
anyOf:
284+
- $id: '#/properties/whitelist/items/anyOf/0'
285+
type: string
286+
title: The first anyOf schema
287+
default: ''
288+
examples:
289+
- /sbin/ping
290+
- ^echo
291+
additionalProperties: true
292+
293+
294+
post:
295+
operationId: executeComponentAction
296+
summary: 'Send a control action to the component'
297+
responses:
298+
200:
299+
description: ''
300+
content:
301+
application/json:
302+
schema:
303+
type: object
304+
additionalProperties: true
305+
306+
example:
307+
runtime: 10.2
308+
309+
/health:
310+
get:
311+
operationId: getHealth
312+
summary: Query health of daemon.
313+
responses:
314+
'200':
315+
description: The daemon is healthy
316+
content:
317+
application/json:
318+
schema:
319+
type: object
320+
properties:
321+
status:
322+
type: string
323+
example:
324+
status: ok

0 commit comments

Comments
 (0)