openapi.yaml · samitouri/QOSami-HFS-2

Code Commits Issues Pulls Sessions CI/CD

main

yaml 1,168 lines 29.4 KB

Raw

1	openapi: 3.0.1
2	info:
3	title: HFS 3
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
8	paths:
9	/~/api/get_file_list:
10	get:
11	summary: List files
12	deprecated: false
13	description: returns all files of a specified folder
14	tags:
15	- Front-end
16	parameters:
17	- name: uri
18	in: query
19	description: path to the folder containing the files. Default is `/`
20	required: false
21	schema:
22	type: string
23	- name: offset
24	in: query
25	description: number of records to skip
26	required: false
27	schema:
28	type: number
29	- name: limit
30	in: query
31	description: max number of records to return
32	required: false
33	schema:
34	type: number
35	- name: search
36	in: query
37	description: search for files with the specified pattern, also in subfolders.
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: >-
62	request separated `c` and `m` properties in entries. Pass any string
63	to turn it on. By default only `m` is provided, and when missing it
64	is copied from `c`.
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
89	content:
90	application/json:
91	schema:
92	$ref: '#/components/schemas/inline_response_200'
93	security: []
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:
111	summary: Login
112	deprecated: false
113	description: clear-text login
114	tags:
115	- Front-end
116	parameters:
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
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
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:
581	upload:
582	type: string
583	description: The file to upload.
584	format: binary
585	encoding:
586	upload:
587	contentType: application/octet-stream
588	responses:
589	'200':
590	description: file uploaded successfully
591	content:
592	application/json:
593	schema:
594	$ref: '#/components/schemas/MultipartUploadResult'
595	'400':
596	description: bad request
597	content:
598	application/json:
599	schema:
600	$ref: '#/components/schemas/MultipartUploadResult'
601	security: []
602	/~/api/add_account:
603	post:
604	summary: add account
605	deprecated: false
606	description: ''
607	tags: []
608	parameters:
609	- name: x-hfs-anti-csrf
610	in: header
611	example: '1'
612	schema:
613	type: string
614	default: '1'
615	requestBody:
616	content:
617	application/json:
618	schema:
619	type: object
620	properties:
621	username:
622	type: string
623	password:
624	type: string
625	belongs:
626	type: array
627	items:
628	type: string
629	ignore_limits:
630	type: boolean
631	disable_password_change:
632	type: boolean
633	admin:
634	type: boolean
635	redirect:
636	type: string
637	disabled:
638	type: boolean
639	expire: &ref_1
640	$ref: '#/components/schemas/Date'
641	days_to_live:
642	type: number
643	overwrite:
644	type: boolean
645	required:
646	- username
647	example:
648	username: john
649	password: betterUseLongPasswords
650	overwrite: false
651	responses:
652	'200':
653	description: Success
654	content:
655	application/json:
656	schema:
657	type: object
658	properties:
659	username:
660	type: string
661	description: returned because it is normalized
662	required:
663	- username
664	security: []
665	/~/api/get_config:
666	get:
667	summary: get config
668	deprecated: false
669	description: ''
670	tags: []
671	parameters:
672	- name: only
673	in: query
674	description: to get only specific keys from the config
675	required: false
676	schema:
677	type: array
678	items:
679	type: string
680	- name: omit
681	in: query
682	description: to get all but the specified keys from the config
683	required: false
684	schema:
685	type: array
686	items:
687	type: string
688	responses:
689	'200':
690	description: Success
691	content:
692	application/json:
693	schema:
694	type: object
695	properties: {}
696	security: []
697	/{folder}/{file}:
698	put:
699	summary: Upload
700	deprecated: false
701	description: Equivalent to curl -T FILE URL/
702	tags:
703	- Front-end
704	parameters:
705	- name: folder
706	in: path
707	description: The folder path where the file will be uploaded
708	required: true
709	example: ''
710	schema:
711	type: string
712	- name: file
713	in: path
714	description: The uploaded file name
715	required: true
716	example: ''
717	schema:
718	type: string
719	- name: existing
720	in: query
721	description: >-
722	Conflict policy when the target file already exists. Use
723	`overwrite` to replace the file if the caller also has delete
724	permission, or `skip` to fail with conflict when the file exists.
725	required: false
726	schema:
727	type: string
728	enum:
729	- overwrite
730	- skip
731	- name: comment
732	in: query
733	description: Comment to store for the uploaded file
734	required: false
735	schema:
736	type: string
737	- name: mtime
738	in: query
739	description: Last modified time to apply to the uploaded file, in Unix milliseconds
740	required: false
741	schema:
742	type: number
743	- name: id
744	in: query
745	description: Client-generated upload identifier used to correlate retries
746	required: false
747	schema:
748	type: string
749	- name: resume
750	in: query
751	description: >-
752	Resume offset for resumable uploads. A trailing `!` asks the server
753	to reject the request when a better resume point is available.
754	required: false
755	schema:
756	type: string
757	- name: partial
758	in: query
759	description: >-
760	Remaining bytes still to be uploaded after this chunk. Used by split
761	and resumable uploads so the server can reserve enough disk space.
762	required: false
763	schema:
764	type: number
765	requestBody:
766	content:
767	application/octet-stream:
768	schema:
769	type: string
770	format: binary
771	responses:
772	'200':
773	description: file uploaded successfully
774	content:
775	application/json:
776	schema:
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:
783	summary: update account
784	deprecated: false
785	description: ''
786	tags: []
787	parameters:
788	- name: x-hfs-anti-csrf
789	in: header
790	example: '1'
791	schema:
792	type: string
793	default: '1'
794	requestBody:
795	content:
796	application/json:
797	schema:
798	type: object
799	properties:
800	username:
801	type: string
802	changes: &ref_0
803	$ref: '#/components/schemas/Account'
804	required:
805	- username
806	- changes
807	example: ''
808	responses:
809	'200':
810	description: Success
811	content:
812	application/json:
813	schema:
814	type: object
815	properties:
816	username:
817	type: string
818	description: returned because it is normalized
819	required:
820	- username
821	security: []
822	/~/api/set_config:
823	post:
824	summary: set config
825	deprecated: false
826	description: ''
827	tags: []
828	parameters:
829	- name: x-hfs-anti-csrf
830	in: header
831	example: '1'
832	schema:
833	type: string
834	default: '1'
835	requestBody:
836	content:
837	application/json:
838	schema:
839	type: object
840	properties:
841	values:
842	type: object
843	properties: {}
844	required:
845	- 01HVXZ10SH9AHVGST5XV79TK5A
846	description: all keys are the defined in config.md file
847	required:
848	- values
849	responses:
850	'200':
851	description: Success
852	content:
853	application/json:
854	schema:
855	type: object
856	properties: {}
857	security: []
858	/~/api/del_account:
859	post:
860	summary: delete account
861	deprecated: false
862	description: ''
863	tags: []
864	parameters:
865	- name: x-hfs-anti-csrf
866	in: header
867	example: '1'
868	schema:
869	type: string
870	default: '1'
871	requestBody:
872	content:
873	application/json:
874	schema:
875	type: object
876	properties:
877	username:
878	type: string
879	required:
880	- username
881	example: ''
882	responses:
883	'200':
884	description: Success
885	content:
886	application/json:
887	schema:
888	type: object
889	properties: {}
890	security: []
891	/~/api/get_accounts:
892	get:
893	summary: list accounts
894	deprecated: false
895	description: ''
896	tags: []
897	parameters: []
898	responses:
899	'200':
900	description: Success
901	content:
902	application/json:
903	schema:
904	type: object
905	properties:
906	list:
907	type: array
908	items: *ref_0
909	required:
910	- list
911	security: []
912	/~/api/get_usernames:
913	get:
914	summary: list usernames
915	deprecated: false
916	description: ''
917	tags: []
918	parameters: []
919	responses:
920	'200':
921	description: Success
922	content:
923	application/json:
924	schema:
925	type: object
926	properties:
927	list:
928	type: array
929	items:
930	type: string
931	required:
932	- list
933	security: []
934	/~/api/get_admins:
935	get:
936	summary: list admins
937	deprecated: false
938	description: ''
939	tags: []
940	parameters: []
941	responses:
942	'200':
943	description: Success
944	content:
945	application/json:
946	schema:
947	type: object
948	properties:
949	list:
950	type: array
951	items:
952	type: string
953	description: username
954	required:
955	- list
956	security: []
957	/~/api/get_account:
958	get:
959	summary: get account
960	deprecated: false
961	description: you can also call this with POST
962	tags: []
963	parameters:
964	- name: username
965	in: query
966	description: ''
967	required: false
968	schema:
969	type: string
970	responses:
971	'200':
972	description: Success
973	content:
974	application/json:
975	schema: *ref_0
976	security: []
977	components:
978	schemas:
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:
1081	username:
1082	type: string
1083	password:
1084	type: string
1085	belongs:
1086	type: array
1087	items:
1088	type: string
1089	ignore_limits:
1090	type: boolean
1091	disable_password_change:
1092	type: boolean
1093	admin:
1094	type: boolean
1095	redirect:
1096	type: string
1097	disabled:
1098	type: boolean
1099	expire: *ref_1
1100	days_to_live:
1101	type: number
1102	required:
1103	- username
1104	folder_body:
1105	type: object
1106	properties:
1107	file:
1108	type: string
1109	description: The file to upload.
1110	format: binary
1111	inline_response_200:
1112	type: object
1113	properties:
1114	can_archive:
1115	type: boolean
1116	description: if you can download this folder as zip
1117	can_upload:
1118	type: boolean
1119	description: if you can upload in this folder
1120	can_delete:
1121	type: boolean
1122	description: if you can delete items in this folder
1123	can_comment:
1124	type: boolean
1125	description: if you can coment items in this folder
1126	list:
1127	type: array
1128	description: entries from this folder
1129	items:
1130	$ref: '#/components/schemas/DirEntry'
1131	DirEntry:
1132	required:
1133	- 'n'
1134	type: object
1135	properties:
1136	'n':
1137	type: string
1138	description: name of the entry. Can be a relative path in case you used `search`.
1139	c:
1140	type: string
1141	description: creation time
1142	format: date-time
1143	m:
1144	type: string
1145	description: modification time
1146	format: date-time
1147	s:
1148	type: number
1149	description: size, in bytes
1150	p:
1151	pattern: '[rR]?[lL]?d?'
1152	type: string
1153	description: \|
1154	permissions, only when are different from the parent folder.
1155	Meaning of each character:
1156	- r: cannot be downloaded
1157	- R: can be downloaded only with other credentials
1158	- l: folder cannot be listed
1159	- L: folder can be listed only with other credetnials
1160	- d: can be deleted
1161	comment:
1162	type: string
1163	description: assigned comment
1164	description: >-
1165	front-end list item format. Common properties are kept short to optimize
1166	space.
1167	securitySchemes: {}
1168	servers: []