8be4dfd8 · samitouri/QOSami-HFS · siGit Code & Deploy

@@ -1,7 +1,7 @@

1 openapi: 3.0.1

2 info:

3 title: HFS 3

4 - description: ''

4 + description: Browser-facing HTTP API used by the HFS frontend and upload flows.

5 version: 1.0.0

6 tags:

7 - name: Front-end

@@ -38,6 +38,24 @@ paths:

38 required: false

39 schema:

40 type: string

41 + - name: searchComment

42 + in: query

43 + description: search for files by comment, also in subfolders.

44 + required: false

45 + schema:

46 + type: string

47 + - name: fileMask

48 + in: query

49 + description: filter files by name mask.

50 + required: false

51 + schema:

52 + type: string

53 + - name: wild

54 + in: query

55 + description: set to `no` to use plain substring matching instead of wildcard matching.

56 + required: false

57 + schema:

58 + type: string

59 - name: c

60 in: query

61 description: >-

@@ -47,6 +65,24 @@ paths:

65 required: false

66 schema:

67 type: string

68 + - name: onlyFolders

69 + in: query

70 + description: return only folders.

71 + required: false

72 + schema:

73 + type: boolean

74 + - name: onlyFiles

75 + in: query

76 + description: return only files.

77 + required: false

78 + schema:

79 + type: boolean

80 + - name: admin

81 + in: query

82 + description: request the list with admin privileges.

83 + required: false

84 + schema:

85 + type: boolean

86 responses:

87 '200':

88 description: all files accordingly to the specified parameters

@@ -55,56 +91,513 @@ paths:

91 schema:

92 $ref: '#/components/schemas/inline_response_200'

93 security: []

58 - /{folder}:

94 + /~/api/refresh_session:

95 + get:

96 + summary: Refresh session

97 + deprecated: false

98 + description: returns the current browser session state

99 + tags:

100 + - Front-end

101 + responses:

102 + '200':

103 + description: current session state

104 + content:

105 + application/json:

106 + schema:

107 + $ref: '#/components/schemas/Session'

108 + security: []

109 + /~/api/login:

110 post:

60 - summary: 'Upload '

111 + summary: Login

112 deprecated: false

62 - description: Equivalent to curl -F upload=@FILE FOLDER/

113 + description: clear-text login

114 tags:

115 - Front-end

116 parameters:

66 - - name: folder

67 - in: path

68 - description: The folder path where the file will be uploaded

117 + - name: x-hfs-anti-csrf

118 + in: header

119 + example: '1'

120 + schema:

121 + type: string

122 + default: '1'

123 + requestBody:

124 + content:

125 + application/json:

126 + schema:

127 + type: object

128 + required:

129 + - username

130 + properties:

131 + username:

132 + type: string

133 + password:

134 + type: string

135 + allow_session_ip_change:

136 + type: boolean

137 + responses:

138 + '200':

139 + description: login succeeded

140 + content:

141 + application/json:

142 + schema:

143 + allOf:

144 + - $ref: '#/components/schemas/Session'

145 + - type: object

146 + properties:

147 + redirect:

148 + type: string

149 + security: []

150 + /~/api/loginSrp1:

151 + post:

152 + summary: Login SRP step 1

153 + deprecated: false

154 + description: returns the server SRP challenge

155 + tags:

156 + - Front-end

157 + parameters:

158 + - name: x-hfs-anti-csrf

159 + in: header

160 + example: '1'

161 + schema:

162 + type: string

163 + default: '1'

164 + requestBody:

165 + content:

166 + application/json:

167 + schema:

168 + type: object

169 + required:

170 + - username

171 + properties:

172 + username:

173 + type: string

174 + responses:

175 + '200':

176 + description: SRP challenge

177 + content:

178 + application/json:

179 + schema:

180 + $ref: '#/components/schemas/SrpStep1'

181 + security: []

182 + /~/api/loginSrp2:

183 + post:

184 + summary: Login SRP step 2

185 + deprecated: false

186 + description: finishes SRP login

187 + tags:

188 + - Front-end

189 + parameters:

190 + - name: x-hfs-anti-csrf

191 + in: header

192 + example: '1'

193 + schema:

194 + type: string

195 + default: '1'

196 + requestBody:

197 + content:

198 + application/json:

199 + schema:

200 + type: object

201 + required:

202 + - pubKey

203 + - proof

204 + properties:

205 + pubKey:

206 + type: string

207 + proof:

208 + type: string

209 + responses:

210 + '200':

211 + description: login succeeded

212 + content:

213 + application/json:

214 + schema:

215 + allOf:

216 + - $ref: '#/components/schemas/Session'

217 + - type: object

218 + required:

219 + - proof

220 + properties:

221 + proof:

222 + type: string

223 + security: []

224 + /~/api/logout:

225 + post:

226 + summary: Logout

227 + deprecated: false

228 + description: clears the current session

229 + tags:

230 + - Front-end

231 + parameters:

232 + - name: x-hfs-anti-csrf

233 + in: header

234 + example: '1'

235 + schema:

236 + type: string

237 + default: '1'

238 + responses:

239 + '401':

240 + description: session cleared

241 + security: []

242 + /~/api/change_srp:

243 + post:

244 + summary: Change password with SRP

245 + deprecated: false

246 + description: updates the current account SRP verifier

247 + tags:

248 + - Front-end

249 + parameters:

250 + - name: x-hfs-anti-csrf

251 + in: header

252 + example: '1'

253 + schema:

254 + type: string

255 + default: '1'

256 + requestBody:

257 + content:

258 + application/json:

259 + schema:

260 + type: object

261 + required:

262 + - username

263 + - salt

264 + - verifier

265 + properties:

266 + username:

267 + type: string

268 + salt:

269 + type: string

270 + verifier:

271 + type: string

272 + responses:

273 + '200':

274 + description: password changed

275 + content:

276 + application/json:

277 + schema:

278 + type: object

279 + properties: {}

280 + security: []

281 + /~/api/get_notifications:

282 + get:

283 + summary: Subscribe to notifications

284 + deprecated: false

285 + description: server-sent events channel used by the frontend

286 + tags:

287 + - Front-end

288 + parameters:

289 + - name: channel

290 + in: query

291 + description: notification channel name

292 required: true

70 - example: ''

293 schema:

294 type: string

295 + responses:

296 + '200':

297 + description: event stream

298 + content:

299 + text/event-stream:

300 + schema:

301 + type: string

302 + security: []

303 + /~/api/get_file_details:

304 + get:

305 + summary: File details

306 + deprecated: false

307 + description: returns extra metadata for one or more file URIs

308 + tags:

309 + - Front-end

310 + parameters:

311 + - name: uris

312 + in: query

313 + description: file URIs to inspect

314 + required: true

315 + style: form

316 + explode: false

317 + schema:

318 + type: array

319 + items:

320 + type: string

321 + responses:

322 + '200':

323 + description: details for the requested URIs

324 + content:

325 + application/json:

326 + schema:

327 + $ref: '#/components/schemas/FileDetailsResponse'

328 + security: []

329 + /~/api/create_folder:

330 + post:

331 + summary: Create folder

332 + deprecated: false

333 + description: creates a new folder inside the specified parent

334 + tags:

335 + - Front-end

336 + parameters:

337 + - name: x-hfs-anti-csrf

338 + in: header

339 + example: '1'

340 + schema:

341 + type: string

342 + default: '1'

343 + requestBody:

344 + content:

345 + application/json:

346 + schema:

347 + type: object

348 + required:

349 + - uri

350 + - name

351 + properties:

352 + uri:

353 + type: string

354 + name:

355 + type: string

356 + responses:

357 + '200':

358 + description: folder created

359 + content:

360 + application/json:

361 + schema:

362 + type: object

363 + properties: {}

364 + security: []

365 + /~/api/rename:

366 + post:

367 + summary: Rename entry

368 + deprecated: false

369 + description: renames a file or folder

370 + tags:

371 + - Front-end

372 + parameters:

373 - name: x-hfs-anti-csrf

374 in: header

75 - description: necessary only for POST requests

375 example: '1'

376 schema:

377 type: string

378 default: '1'

379 + requestBody:

380 + content:

381 + application/json:

382 + schema:

383 + type: object

384 + required:

385 + - uri

386 + - dest

387 + properties:

388 + uri:

389 + type: string

390 + dest:

391 + type: string

392 + responses:

393 + '200':

394 + description: rename completed

395 + content:

396 + application/json:

397 + schema:

398 + type: object

399 + properties: {}

400 + security: []

401 + /~/api/move_files:

402 + post:

403 + summary: Move files

404 + deprecated: false

405 + description: moves one or more files to another folder

406 + tags:

407 + - Front-end

408 + parameters:

409 + - name: x-hfs-anti-csrf

410 + in: header

411 + example: '1'

412 + schema:

413 + type: string

414 + default: '1'

415 + requestBody:

416 + content:

417 + application/json:

418 + schema:

419 + type: object

420 + required:

421 + - uri_from

422 + - uri_to

423 + properties:

424 + uri_from:

425 + type: array

426 + items:

427 + type: string

428 + uri_to:

429 + type: string

430 + responses:

431 + '200':

432 + description: move results

433 + content:

434 + application/json:

435 + schema:

436 + $ref: '#/components/schemas/MoveFilesResponse'

437 + security: []

438 + /~/api/copy_files:

439 + post:

440 + summary: Copy files

441 + deprecated: false

442 + description: copies one or more files to another folder

443 + tags:

444 + - Front-end

445 + parameters:

446 + - name: x-hfs-anti-csrf

447 + in: header

448 + example: '1'

449 + schema:

450 + type: string

451 + default: '1'

452 + requestBody:

453 + content:

454 + application/json:

455 + schema:

456 + type: object

457 + required:

458 + - uri_from

459 + - uri_to

460 + properties:

461 + uri_from:

462 + type: array

463 + items:

464 + type: string

465 + uri_to:

466 + type: string

467 + responses:

468 + '200':

469 + description: copy results

470 + content:

471 + application/json:

472 + schema:

473 + $ref: '#/components/schemas/MoveFilesResponse'

474 + security: []

475 + /~/api/comment:

476 + post:

477 + summary: Set comment

478 + deprecated: false

479 + description: stores a comment for a file or folder

480 + tags:

481 + - Front-end

482 + parameters:

483 + - name: x-hfs-anti-csrf

484 + in: header

485 + example: '1'

486 + schema:

487 + type: string

488 + default: '1'

489 + requestBody:

490 + content:

491 + application/json:

492 + schema:

493 + type: object

494 + required:

495 + - uri

496 + - comment

497 + properties:

498 + uri:

499 + type: string

500 + comment:

501 + type: string

502 + responses:

503 + '200':

504 + description: comment saved

505 + content:

506 + application/json:

507 + schema:

508 + type: object

509 + properties: {}

510 + security: []

511 + /~/api/get_folder_size:

512 + get:

513 + summary: Folder size

514 + deprecated: false

515 + description: calculates the total size of a folder

516 + tags:

517 + - Front-end

518 + parameters:

519 + - name: uri

520 + in: query

521 + required: true

522 + schema:

523 + type: string

524 + - name: id

525 + in: query

526 + required: true

527 + schema:

528 + type: string

529 + responses:

530 + '200':

531 + description: folder size

532 + content:

533 + application/json:

534 + schema:

535 + $ref: '#/components/schemas/FolderSize'

536 + security: []

537 + /~/api/get_folder_size_partial:

538 + get:

539 + summary: Folder size progress

540 + deprecated: false

541 + description: returns partial progress for an in-flight folder size computation

542 + tags:

543 + - Front-end

544 + parameters:

545 + - name: id

546 + in: query

547 + required: true

548 + schema:

549 + type: string

550 + responses:

551 + '200':

552 + description: current partial progress

553 + content:

554 + application/json:

555 + schema:

556 + $ref: '#/components/schemas/FolderSize'

557 + '404':

558 + description: computation not found anymore

559 + security: []

560 + /{folder}:

561 + post:

562 + summary: Upload

563 + deprecated: false

564 + description: Equivalent to curl -F upload=@FILE FOLDER/

565 + tags:

566 + - Front-end

567 + parameters:

568 + - name: folder

569 + in: path

570 + description: The folder path where the file will be uploaded

571 + required: true

572 + example: ''

573 + schema:

574 + type: string

575 requestBody:

576 content:

577 multipart/form-data:

578 schema:

579 type: object

580 properties:

86 - file:

581 + upload:

582 type: string

583 description: The file to upload.

584 format: binary

585 encoding:

91 - file:

586 + upload:

587 contentType: application/octet-stream

588 responses:

589 '200':

95 - description: File uploaded successfully

590 + description: file uploaded successfully

591 content:

592 application/json:

593 schema:

99 - type: object

100 - properties: {}

594 + $ref: '#/components/schemas/MultipartUploadResult'

595 '400':

102 - description: Bad request

596 + description: bad request

597 content:

598 application/json:

599 schema:

106 - type: object

107 - properties: {}

600 + $ref: '#/components/schemas/MultipartUploadResult'

601 security: []

602 /~/api/add_account:

603 post:

@@ -115,7 +608,6 @@ paths:

608 parameters:

609 - name: x-hfs-anti-csrf

610 in: header

118 - description: necessary only for POST requests

611 example: '1'

612 schema:

613 type: string

@@ -278,12 +770,13 @@ paths:

770 format: binary

771 responses:

772 '200':

281 - description: File uploaded successfully

773 + description: file uploaded successfully

774 content:

775 application/json:

776 schema:

285 - type: object

286 - properties: {}

777 + $ref: '#/components/schemas/UploadResult'

778 + '204':

779 + description: partial upload chunk stored without finalizing the file

780 security: []

781 /~/api/set_account:

782 post:

@@ -294,7 +787,6 @@ paths:

787 parameters:

788 - name: x-hfs-anti-csrf

789 in: header

297 - description: necessary only for POST requests

790 example: '1'

791 schema:

792 type: string

@@ -336,7 +828,6 @@ paths:

828 parameters:

829 - name: x-hfs-anti-csrf

830 in: header

339 - description: necessary only for POST requests

831 example: '1'

832 schema:

833 type: string

@@ -373,44 +864,6 @@ paths:

864 parameters:

865 - name: x-hfs-anti-csrf

866 in: header

376 - description: necessary only for POST requests

377 - example: '1'

378 - schema:

379 - type: string

380 - default: '1'

381 - requestBody:

382 - content:

383 - application/json:

384 - schema:

385 - type: object

386 - properties:

387 - username:

388 - type: string

389 - required:

390 - - username

391 - example: ''

392 - responses:

393 - '200':

394 - description: Success

395 - content:

396 - application/json:

397 - schema:

398 - type: object

399 - properties: {}

400 - security: []

401 - /~/api/change_srp:

402 - post:

403 - summary: safer update of the password

404 - deprecated: false

405 - description: >-

406 - use SRP protocol to change the password without transmitting it. If your

407 - channel is trusted, you can just specify 'password' in set_account or

408 - add_account, that's much simpler.

409 - tags: []

410 - parameters:

411 - - name: x-hfs-anti-csrf

412 - in: header

413 - description: necessary only for POST requests

867 example: '1'

868 schema:

869 type: string

@@ -423,14 +876,8 @@ paths:

876 properties:

877 username:

878 type: string

426 - salt:

427 - type: string

428 - verifier:

429 - type: string

879 required:

880 - username

432 - - salt

433 - - verifier

881 example: ''

882 responses:

883 '200':

@@ -532,6 +979,102 @@ components:

979 Date:

980 type: string

981 format: date-time

982 + Session:

983 + type: object

984 + properties:

985 + username:

986 + type: string

987 + expandedUsername:

988 + type: array

989 + items:

990 + type: string

991 + adminUrl:

992 + type: string

993 + canChangePassword:

994 + type: boolean

995 + requireChangePassword:

996 + type: boolean

997 + exp:

998 + $ref: '#/components/schemas/Date'

999 + accountExp:

1000 + $ref: '#/components/schemas/Date'

1001 + redirect:

1002 + type: string

1003 + SrpStep1:

1004 + type: object

1005 + required:

1006 + - salt

1007 + - pubKey

1008 + properties:

1009 + salt:

1010 + type: string

1011 + pubKey:

1012 + type: string

1013 + UploadResult:

1014 + type: object

1015 + required:

1016 + - uri

1017 + properties:

1018 + uri:

1019 + type: string

1020 + MultipartUploadResult:

1021 + type: object

1022 + properties:

1023 + uris:

1024 + type: array

1025 + items:

1026 + type: string

1027 + errors:

1028 + type: array

1029 + items:

1030 + type: string

1031 + FolderSize:

1032 + type: object

1033 + required:

1034 + - bytes

1035 + - files

1036 + - folders

1037 + properties:

1038 + bytes:

1039 + type: number

1040 + files:

1041 + type: number

1042 + folders:

1043 + type: number

1044 + UploadMeta:

1045 + type: object

1046 + properties:

1047 + username:

1048 + type: string

1049 + ip:

1050 + type: string

1051 + FileDetails:

1052 + type: object

1053 + properties:

1054 + upload:

1055 + $ref: '#/components/schemas/UploadMeta'

1056 + FileDetailsResponse:

1057 + type: object

1058 + required:

1059 + - details

1060 + properties:

1061 + details:

1062 + type: array

1063 + items:

1064 + oneOf:

1065 + - type: boolean

1066 + enum:

1067 + - false

1068 + - $ref: '#/components/schemas/FileDetails'

1069 + MoveFilesResponse:

1070 + type: object

1071 + properties:

1072 + errors:

1073 + type: array

1074 + items:

1075 + oneOf:

1076 + - type: integer

1077 + - type: string

1078 Account:

1079 type: object

1080 properties:

doc: added frontend APIs