/
OpenAPI.yaml
448 lines (444 loc) · 17.6 KB
/
OpenAPI.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
openapi: 3.0.0
info:
version: '3.5.0'
title: 'DuetSoftwareFramework'
license:
name: GPL-3.0
paths:
/machine/connect:
get:
summary: |
Establish a connection to the SBC and check the given password. The default password (in case none is set) is `reprap`. If no password is expected, the `password` key can be omitted.
For following HTTP requests, the session key must be added to the HTTP headers via `X-Session-Key`. For WebSocket requests, it must be appended to the URL using the `sessionKey` parameter (e.g. `ws://duet3/machine?sessionKey=<KEY>`).
The resulting session is maintained at least 8 seconds but it may last as long as
- a WebSocket is open
- a long-running HTTP request is being processed (code, upload, and package requests)
parameters:
- name: password
in: query
description: Password
required: false
schema:
type: string
format: password
responses:
'200':
description: 'Connect response'
content:
application/json:
schema:
type: object
properties:
sessionKey:
type: string
'403':
description: 'Forbidden (invalid password)'
'500':
description: 'Generic error'
'502':
description: 'Incompatible DCS version'
'503':
description: 'DCS is unavailable'
/machine/noop:
get:
summary: |
Do nothing. May be used to ping the machine or to keep the HTTP session alive
responses:
'204':
description: 'No Content'
'403':
description: 'Forbidden (missing or invalid `X-Session-Key` header)'
/machine/disconnect:
get:
summary: |
Disconnect from the machine
responses:
'204':
description: 'No Content'
'500':
description: 'Generic error'
'502':
description: 'Incompatible DCS version'
'503':
description: 'DCS is unavailable'
/machine/model:
get:
summary: |
Query the full object model
responses:
'200':
description: 'Query OK, current object model is returned as application/json'
content:
application/json: {}
'403':
description: 'Forbidden (missing or invalid X-Session-Key header)'
/machine/status:
get:
summary: |
Query the full object model (equivalent to /machine/model, not supported before v3.4.6 or v3.5-b4)
responses:
'200':
description: 'Query OK, current object model is returned as application/json'
content:
application/json: {}
'403':
description: 'Forbidden (missing or invalid X-Session-Key header)'
/machine/code:
get:
summary: |
Execute plain G/M/T-code(s) from the raw request body and return the G-code response when done.
The optional `async` parameter defines whether the request shall block until the code has been executed.
If it is set to `true` and a code reply is generated, the reply is output as a generic message
parameters:
- name: async
in: query
description: 'Execute the code(s) asynchronously'
required: false
schema:
type: boolean
responses:
'200':
description: 'Code(s) have finished, reply is returned as `text/plain`'
content:
text/plain: {}
'403':
description: 'Forbidden (missing or invalid X-Session-Key header)'
'500':
description: 'Generic error'
'502':
description: 'Incompatible DCS version'
'503':
description: 'DCS is unavailable'
/machine/file/{filename}:
get:
summary: |
Download a file. The file path is translated to a physical file path
parameters:
- name: filename
in: path
description: 'Name of the file to download'
required: true
schema:
type: string
responses:
'200':
description: 'File content'
content:
application/octet-stream: {}
'403':
description: 'Forbidden (missing or invalid X-Session-Key header)'
'404':
description: 'File not found'
'500':
description: 'Generic error'
'502':
description: 'Incompatible DCS version'
'503':
description: 'DCS is unavailable'
put:
summary: |
Upload a file. The file path is translated to a physical file path. The body payload is the file content
parameters:
- name: filename
in: path
description: 'Name of the file to upload'
required: true
schema:
type: string
- name: timeModified
in: query
description: Optional timestamp of the file
required: false
schema:
type: string
format: date-time
requestBody:
description: 'Content of the file to upload'
content:
application/octet-stream: {}
responses:
'201':
description: 'File created'
'403':
description: 'Forbidden (missing or invalid X-Session-Key header)'
'500':
description: 'Generic error'
'502':
description: 'Incompatible DCS version'
'503':
description: 'DCS is unavailable'
delete:
summary: |
Delete a file or directory. The file path is translated to a physical file path
parameters:
- name: filename
in: path
description: 'Name of the file to delete'
required: true
schema:
type: string
- name: recursive
in: query
description: 'Whether the directory shall be deleted recursively'
required: false
responses:
'204':
description: 'File or directory succesfully deleted'
'403':
description: 'Forbidden (missing or invalid X-Session-Key header)'
'404':
description: 'File not found'
'500':
description: 'Generic error'
'502':
description: 'Incompatible DCS version'
'503':
description: 'DCS is unavailable'
/machine/fileinfo/{filename}:
get:
summary: |
Parse a given G-code file and return information about this job file as a JSON object.
See [API Documentation](https://duet3d.github.io/DuetSoftwareFramework/api/DuetAPI.Machine.ParsedFileInfo.html) for further information about the object returned
parameters:
- name: filename
in: path
description: 'Name of the file to parse'
required: true
schema:
type: string
responses:
'200':
description: 'Parsed file information as `application/json`'
content:
application/json: {}
'403':
description: 'Forbidden (missing or invalid X-Session-Key header)'
'404':
description: 'File not found'
'500':
description: 'Generic error'
'502':
description: 'Incompatible DCS version'
'503':
description: 'DCS is unavailable'
/machine/file/move:
post:
summary: |
Move a file or directory from a to b. The file paths are translated to physical file paths
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
from:
description: 'Source file path'
type: string
to:
description: 'Destination file path'
type: string
force:
description: 'If the destination file already exists, delete it first. Defaults to false'
type: boolean
required: ['from', 'to']
responses:
'204':
description: 'File or directory succesfully moved'
'403':
description: 'Forbidden (missing or invalid X-Session-Key header)'
'404':
description: 'File not found'
'500':
description: 'Generic error'
'502':
description: 'Incompatible DCS version'
'503':
description: 'DCS is unavailable'
/machine/directory/{directory}:
get:
summary: |
Get a file list of the given directory. The directory path is translated to a physical file path
parameters:
- name: directory
in: path
description: 'Name of the directory to list'
required: true
schema:
type: string
responses:
'200':
description: 'File list of the directory`'
content:
application/json:
schema:
type: array
items:
type: object
properties:
type:
type: string
enum:
- d
- f
name:
type: string
date:
type: string
format: 'date-time'
'403':
description: 'Forbidden (missing or invalid X-Session-Key header)'
'404':
description: 'File not found'
'500':
description: 'Generic error'
'502':
description: 'Incompatible DCS version'
'503':
description: 'DCS is unavailable'
put:
summary: |
Create the given directory. The directory path is translated to a physical directory path
parameters:
- name: directory
in: path
description: 'Name of the directory to create'
required: true
schema:
type: string
responses:
'201':
description: 'Directory created'
'403':
description: 'Forbidden (missing or invalid X-Session-Key header)'
'404':
description: 'File not found'
'500':
description: 'Generic error'
'502':
description: 'Incompatible DCS version'
'503':
description: 'DCS is unavailable'
/machine/plugin:
put:
summary: |
Install or upgrade a plugin ZIP file
requestBody:
description: 'Plugin ZIP content'
content:
application/octet-stream: {}
responses:
'204':
description: 'Plugin has been installed'
'403':
description: 'Forbidden (missing or invalid X-Session-Key header)'
'500':
description: 'Generic error'
'502':
description: 'Incompatible DCS version'
'503':
description: 'DCS is unavailable'
delete:
summary: |
Uninstall a plugin
requestBody:
description: 'Name of the plugin to uninstall'
content:
text/plain: {}
responses:
'204':
description: 'Plugin has been uninstalled'
'403':
description: 'Forbidden (missing or invalid X-Session-Key header)'
'500':
description: 'Generic error'
'502':
description: 'Incompatible DCS version'
'503':
description: 'DCS is unavailable'
patch:
summary: |
Set plugin data in the object model if there is no SBC executable.
If there is an SBC executable, expose your own HTTP endpoints to modify shared plugin data.
requestBody:
content:
application/json:
schema:
properties:
plugin:
type: string
key:
type: string
value: {}
responses:
'204':
description: 'Data has been set'
'403':
description: 'Forbidden (missing or invalid X-Session-Key header)'
'500':
description: 'Generic error'
'502':
description: 'Incompatible DCS version'
'503':
description: 'DCS is unavailable'
/machine/startPlugin:
post:
description: |
Start a plugin on the SBC. This does nothing if a plugin has already been started
requestBody:
description: 'Name of the plugin to start'
content:
'text/plain': {}
responses:
'204':
description: 'Plugin has been started'
'403':
description: 'Forbidden (missing or invalid X-Session-Key header)'
'500':
description: 'Generic error'
'502':
description: 'Incompatible DCS version'
'503':
description: 'DCS is unavailable'
/machine/stopPlugin:
post:
description: |
Stop a plugin on the SBC. This does nothing if a plugin has already been stopped
requestBody:
description: 'Name of the plugin to stop'
content:
'text/plain': {}
responses:
'204':
description: 'Plugin has been stop'
'403':
description: 'Forbidden (missing or invalid X-Session-Key header)'
'500':
description: 'Generic error'
'502':
description: 'Incompatible DCS version'
'503':
description: 'DCS is unavailable'
components:
securitySchemes:
SessionKey:
type: "apiKey"
description: "API key returned from the connect response (optional if no password is set)"
in: "header"
name: "X-Session-Key"
servers:
- url: 'http://duet3'
description: 'Duet 3 in SBC mode'
security:
- SessionKey: [
'/machine/noop',
'/machine/disconnect',
'/machine/status',
'/machine/code',
'/machine/file/{filename}',
'/machine/fileinfo/{filename}',
'/machine/file/move',
'/machine/directory/{directory}',
'/machine/plugin',
'/machine/startPlugin',
'/machine/stopPlugin'
]