From 5c4c2528aef8d6a3c5ccab89a181012f95302fbc Mon Sep 17 00:00:00 2001 From: Wim Brand Date: Wed, 4 Jul 2018 22:46:51 +0200 Subject: [PATCH] add api documentation for directory api --- res/template/apidoc.html | 9 +- res/template/fragments/api/directory.html | 155 +++++++++++ .../fragments/api/file-id-delete.html | 51 ---- .../fragments/api/file-id-download-get.html | 13 - res/template/fragments/api/file-id-get.html | 29 -- .../fragments/api/file-id-info-get.html | 49 ---- .../fragments/api/file-id-thumbnail-get.html | 34 --- res/template/fragments/api/file-post.html | 73 ----- res/template/fragments/api/file.html | 249 ++++++++++++++++++ res/template/fragments/api/list-get.html | 78 ------ .../api/{list-post.html => list.html} | 82 +++++- 11 files changed, 490 insertions(+), 332 deletions(-) create mode 100644 res/template/fragments/api/directory.html delete mode 100644 res/template/fragments/api/file-id-delete.html delete mode 100644 res/template/fragments/api/file-id-download-get.html delete mode 100644 res/template/fragments/api/file-id-get.html delete mode 100644 res/template/fragments/api/file-id-info-get.html delete mode 100644 res/template/fragments/api/file-id-thumbnail-get.html delete mode 100644 res/template/fragments/api/file-post.html create mode 100644 res/template/fragments/api/file.html delete mode 100644 res/template/fragments/api/list-get.html rename res/template/fragments/api/{list-post.html => list.html} (53%) diff --git a/res/template/apidoc.html b/res/template/apidoc.html index 624da7d..da21d1d 100644 --- a/res/template/apidoc.html +++ b/res/template/apidoc.html @@ -17,9 +17,7 @@ don't require an API key. All methods which delete or modify a resource do require an API key.
-
- Though API keys have not been implemented yet, so you can't use - those methods yet. + API keys can be obtained from the login API.

Some JSON responses include fields which end in "_href" (some @@ -46,6 +44,11 @@ {{template "api-list-post"}} {{template "api-list-get"}} +

Directory Methods

+ {{template "api-directory-path-post"}} + {{template "api-directory-path-get"}} + {{template "api-directory-path-delete"}} + {{template "footer"}} {{template "analytics"}} diff --git a/res/template/fragments/api/directory.html b/res/template/fragments/api/directory.html new file mode 100644 index 0000000..246f249 --- /dev/null +++ b/res/template/fragments/api/directory.html @@ -0,0 +1,155 @@ +{{define "api-directory-path-post"}} +
+ POST/directory/{path} +
+

Description

+

+ Creates a new directory or uploads a file to an existing directory. +

+ +

Parameters

+ + + + + + + + + + + + + + + + + + + + + +
ParamLocationDescription
typeForm ValuesThe type of node to create, can either be 'directory', or 'file'
nameForm Values + Name of the directory to create, or of file to create. Not + required if 'type' is 'file' +
fileForm Values + Multipart file to upload to the directory. Will be ignored + if 'type' is 'directory' +
+ +

Returns

+
HTTP 200: OK
+{
+	"success": true,
+	"id": "abc123" // ID of the newly uploaded file
+}
+ todo +
+
+{{end}} +{{define "api-directory-path-get"}} +
+ GET/directory/{path} +
+

Description

+

+ Returns information about the requested path. +

+

Parameters

+ + + + + + + + + + + + + + + + + + + +
ParamRequiredLocationDescription
pathtrueURLPath to the directory or file to request
downloadfalseURL + If the URL paramater '?download' is passed the requested + file will be downloaded (if it is a file) +
+

Returns

+

When the requested entity is a directory:

+ 
HTTP 200: OK
+{
+	"success": true,
+	"name": "some dir",
+	"path": "/some dir",
+	"type": "directory",
+	"child_directories": [
+		{
+			"name": "some other directory",
+			"path": "/some dir/some other directory"
+		}
+	],
+	"child_files": [
+		{
+			"name": "11. Lenny Kravitz - Fly away.ogg",
+			"path": "/some dir/11. Lenny Kravitz - Fly away.ogg"
+		}
+	]
+}
+

When the requested entity is a file:

+ 
HTTP 200: OK
+{
+	"success": true,
+	"name": "11. Lenny Kravitz - Fly away.ogg",
+	"path": "/some dir/11. Lenny Kravitz - Fly away.ogg",
+	"type": "file",
+	"file_info": {
+		"success": true,
+		"id": "Jf_u5TI9",
+		"file_name": "11. Lenny Kravitz - Fly away.ogg",
+		"date_upload": "2018-07-04T22:24:48Z",
+		"date_last_view": "2018-07-04T22:24:48Z",
+		"file_size": 9757269,
+		"views": 0,
+		"mime_type": "application/ogg",
+		"thumbnail_href": "/file/Jf_u5TI9/thumbnail"
+	}
+}
+
+
+{{end}} +{{define "api-directory-path-delete"}} +
+ DELETE/directory/{path} +
+

Description

+

+ Deletes a filesystem node. +

+

Parameters

+ + + + + + + + + + + + + +
ParamRequiredLocationDescription
pathtrueURLPath of the entity to delete
+

Returns

+
HTTP 200: OK
+{
+	"success": true
+}
+
+
+{{end}} diff --git a/res/template/fragments/api/file-id-delete.html b/res/template/fragments/api/file-id-delete.html deleted file mode 100644 index db4ca9c..0000000 --- a/res/template/fragments/api/file-id-delete.html +++ /dev/null @@ -1,51 +0,0 @@ -{{define "api-file-id-delete"}} -
- DELETE/file/{id} -
-

Description

-

- Deletes a file. Only works when the users owns the file. -

-

Parameters

- - - - - - - - - - - - - -
ParamRequiredLocationDescription
idtrueURLID of the file to delete
-

Returns

-
HTTP 200: OK
-{
-	"success": true,
-	"value": "file_deleted",
-	"message": "The file has been deleted."
-}
-
HTTP 404: Not Found
-{
-	"success": false,
-	"value": "file_not_found",
-	"message": "File ID was not found in the database."
-}
-
HTTP 401: Unauthorized
-{
-	"success": false,
-	"value": "unauthorized",
-	"message": "You are not logged in."
-}
-
HTTP 403: Forbidden
-{
-	"success": false,
-	"value": "forbidden",
-	"message": "This is not your file."
-}
-
-
-{{end}} \ No newline at end of file diff --git a/res/template/fragments/api/file-id-download-get.html b/res/template/fragments/api/file-id-download-get.html deleted file mode 100644 index 70d4d04..0000000 --- a/res/template/fragments/api/file-id-download-get.html +++ /dev/null @@ -1,13 +0,0 @@ -{{define "api-file-id-download-get"}} -
- GET/file/{id}/download -
-

Description

-

- Same as GET /file/{id}, but with File Transfer HTTP - headers. Will trigger a save file dialog when opened in - a web browser. Also supports byte range requests. -

-
-
-{{end}} \ No newline at end of file diff --git a/res/template/fragments/api/file-id-get.html b/res/template/fragments/api/file-id-get.html deleted file mode 100644 index a6a3781..0000000 --- a/res/template/fragments/api/file-id-get.html +++ /dev/null @@ -1,29 +0,0 @@ -{{define "api-file-id-get"}} -
- GET/file/{id} -
-

Description

-

- Returns the full file associated with the ID. Supports - byte range requests. -

-

Parameters

- - - - - - - - - - - - - -
ParamRequiredLocationDescription
idtrueURLID of the file to request
-

Returns

- A file output stream. -
-
-{{end}} \ No newline at end of file diff --git a/res/template/fragments/api/file-id-info-get.html b/res/template/fragments/api/file-id-info-get.html deleted file mode 100644 index 3c65fca..0000000 --- a/res/template/fragments/api/file-id-info-get.html +++ /dev/null @@ -1,49 +0,0 @@ -{{define "api-file-id-info-get"}} -
- GET/file/{id}/info -
-

Description

-

- Returns information about one or more files. - You can also put a comma separated list of file IDs in - the URL and it will return an array of file info, - instead of a single object. -

-

Parameters

- - - - - - - - - - - - - -
ParamRequiredLocationDescription
idtrueURLID(s) of the file
-

Returns

-
HTTP 200: OK
-{
-	"success": true,
-	"id": "123abc",
-	"file_name": "screenshot.png",
-	"date_upload": 1485894987, // Timestamp
-	"date_last_view": 1485894987, // Timestamp
-	"file_size": 5694837, // Bytes
-	"views" 1234, // Amount of unique file views
-	"mime_type" "image/png",
-	"description": "File description",
-	"mime_image": "http://pixeldra.in/res/img/mime/image-png.png", // Image associated with the mime type
-	"thumbnail": "http://pixeldra.in/api/thumbnail/123abc" // Link to a thumbnail of this file
-}
-
HTTP 404: Not Found
-{
-	"success": false,
-	"value": "file_not_found"
-}
-
-
-{{end}} \ No newline at end of file diff --git a/res/template/fragments/api/file-id-thumbnail-get.html b/res/template/fragments/api/file-id-thumbnail-get.html deleted file mode 100644 index 66f2299..0000000 --- a/res/template/fragments/api/file-id-thumbnail-get.html +++ /dev/null @@ -1,34 +0,0 @@ -{{define "api-file-id-thumbnail-get"}} -
- GET/file/{id}/thumbnail -
-

Description

-

- Returns a PNG thumbnail image representing the file. - The thumbnail is always 100*100 px. If the source file - is parsable by imagemagick the thumbnail will be - generated from the file, if not it will be a generic - mime type icon. -

-

Parameters

- - - - - - - - - - - - - -
ParamRequiredLocationDescription
idtrueURLID of the file to get a thumbnail for
-

Returns

-

- A PNG image of 100*100 px. -

-
-
-{{end}} \ No newline at end of file diff --git a/res/template/fragments/api/file-post.html b/res/template/fragments/api/file-post.html deleted file mode 100644 index e4c64a8..0000000 --- a/res/template/fragments/api/file-post.html +++ /dev/null @@ -1,73 +0,0 @@ -{{define "api-file-post"}} -
- POST/file -
-

Description

-

- Upload a file. -

- -

Parameters

- - - - - - - - - - - - - - - - - - - - - - -
ParamRequiredMaximum SizeDefaultDescription
filetrue5 000 000 000 BytesnoneMultipart file to upload
namefalse255 CharactersMultipart file nameName of the file to upload
- -

Returns

-
HTTP 200: OK
-{
-	"success": true,
-	"id": "abc123" // ID of the newly uploaded file
-}
-
HTTP 422: Unprocessable Entity
-{
-	"success": false,
-	"value": "no_file",
-	"message": "The file does not exist or is empty."
-}
-
HTTP 500: Internal Server Error
-{
-	"success": false,
-	"value": "internal",
-	"message": "An internal server error occurred."
-}
-
HTTP 413: Payload Too Large
-{
-	"success": false,
-	"value": "file_too_large",
-	"message": "The file you tried to upload is too large. Max 5000 MB allowed."
-}
-
HTTP 500: Internal Server Error
-{
-	"success": false,
-	"value": "writing",
-	"message": "Something went wrong while writing the file to disk, the server may be out of storage space."
-}
-
HTTP 413: Payload Too Large
-{
-	"success": false,
-	"value": "name_too_long",
-	"message": "File Name is too long, Max 255 characters allowed."
-}
-
-
-{{end}} \ No newline at end of file diff --git a/res/template/fragments/api/file.html b/res/template/fragments/api/file.html new file mode 100644 index 0000000..fb0f1f8 --- /dev/null +++ b/res/template/fragments/api/file.html @@ -0,0 +1,249 @@ +{{define "api-file-post"}} +
+ POST/file +
+

Description

+

+ Upload a file. +

+ +

Parameters

+ + + + + + + + + + + + + + + + + + + + + + +
ParamRequiredMaximum SizeDefaultDescription
filetrue5 000 000 000 BytesnoneMultipart file to upload
namefalse255 CharactersMultipart file nameName of the file to upload
+ +

Returns

+
HTTP 200: OK
+{
+	"success": true,
+	"id": "abc123" // ID of the newly uploaded file
+}
+
HTTP 422: Unprocessable Entity
+{
+	"success": false,
+	"value": "no_file",
+	"message": "The file does not exist or is empty."
+}
+
HTTP 500: Internal Server Error
+{
+	"success": false,
+	"value": "internal",
+	"message": "An internal server error occurred."
+}
+
HTTP 413: Payload Too Large
+{
+	"success": false,
+	"value": "file_too_large",
+	"message": "The file you tried to upload is too large. Max 5000 MB allowed."
+}
+
HTTP 500: Internal Server Error
+{
+	"success": false,
+	"value": "writing",
+	"message": "Something went wrong while writing the file to disk, the server may be out of storage space."
+}
+
HTTP 413: Payload Too Large
+{
+	"success": false,
+	"value": "name_too_long",
+	"message": "File Name is too long, Max 255 characters allowed."
+}
+
+
+{{end}} +{{define "api-file-id-get"}} +
+ GET/file/{id} +
+

Description

+

+ Returns the full file associated with the ID. Supports + byte range requests. +

+

Parameters

+ + + + + + + + + + + + + +
ParamRequiredLocationDescription
idtrueURLID of the file to request
+

Returns

+ A file output stream. +
+
+{{end}} +{{define "api-file-id-download-get"}} +
+ GET/file/{id}/download +
+

Description

+

+ Same as GET /file/{id}, but with File Transfer HTTP + headers. Will trigger a save file dialog when opened in + a web browser. Also supports byte range requests. +

+
+
+{{end}} +{{define "api-file-id-info-get"}} +
+ GET/file/{id}/info +
+

Description

+

+ Returns information about one or more files. + You can also put a comma separated list of file IDs in + the URL and it will return an array of file info, + instead of a single object. +

+

Parameters

+ + + + + + + + + + + + + +
ParamRequiredLocationDescription
idtrueURLID(s) of the file
+

Returns

+
HTTP 200: OK
+{
+	"success": true,
+	"id": "123abc",
+	"file_name": "screenshot.png",
+	"date_upload": 1485894987, // Timestamp
+	"date_last_view": 1485894987, // Timestamp
+	"file_size": 5694837, // Bytes
+	"views" 1234, // Amount of unique file views
+	"mime_type" "image/png",
+	"description": "File description",
+	"mime_image": "http://pixeldra.in/res/img/mime/image-png.png", // Image associated with the mime type
+	"thumbnail": "http://pixeldra.in/api/thumbnail/123abc" // Link to a thumbnail of this file
+}
+
HTTP 404: Not Found
+{
+	"success": false,
+	"value": "file_not_found"
+}
+
+
+{{end}} +{{define "api-file-id-thumbnail-get"}} +
+ GET/file/{id}/thumbnail +
+

Description

+

+ Returns a PNG thumbnail image representing the file. + The thumbnail is always 100*100 px. If the source file + is parsable by imagemagick the thumbnail will be + generated from the file, if not it will be a generic + mime type icon. +

+

Parameters

+ + + + + + + + + + + + + +
ParamRequiredLocationDescription
idtrueURLID of the file to get a thumbnail for
+

Returns

+

+ A PNG image of 100*100 px. +

+
+
+{{end}} +{{define "api-file-id-delete"}} +
+ DELETE/file/{id} +
+

Description

+

+ Deletes a file. Only works when the users owns the file. +

+

Parameters

+ + + + + + + + + + + + + +
ParamRequiredLocationDescription
idtrueURLID of the file to delete
+

Returns

+
HTTP 200: OK
+{
+	"success": true,
+	"value": "file_deleted",
+	"message": "The file has been deleted."
+}
+
HTTP 404: Not Found
+{
+	"success": false,
+	"value": "file_not_found",
+	"message": "File ID was not found in the database."
+}
+
HTTP 401: Unauthorized
+{
+	"success": false,
+	"value": "unauthorized",
+	"message": "You are not logged in."
+}
+
HTTP 403: Forbidden
+{
+	"success": false,
+	"value": "forbidden",
+	"message": "This is not your file."
+}
+
+
+{{end}} diff --git a/res/template/fragments/api/list-get.html b/res/template/fragments/api/list-get.html deleted file mode 100644 index 0f7778b..0000000 --- a/res/template/fragments/api/list-get.html +++ /dev/null @@ -1,78 +0,0 @@ -{{define "api-list-get"}} -
- GET/list/{id} -
-

Description

-

- Returns information about a file list and the files in it. -

-

Parameters

- - - - - - - - - - - - - -
ParamRequiredLocationDescription
idtrueURLID of the list
-

Returns

-

- The API will return some basic information about every file. - Every file also has a "detail_href" field which contains a URL - to the info API of the file. Follow that link to get more - information about the file like size, checksum, mime type, etc. - The address is relative to the API URL and should be appended to - the end. -

-
HTTP 200: OK
-{
-	"success": true,
-	"id": "L8bhwx",
-	"title": "Rust in Peace",
-	"date_created": 1513033315,
-	"files": [
-		{
-			"detail_href": "/file/_SqVWi/info",
-			"id": "_SqVWi",
-			"file_name": "01 Holy Wars... The Punishment Due.mp3",
-			"description": "",
-			"date_created": 1513033304,
-			"date_last_view": 1513033304,
-			"list_description": ""
-		},
-		{
-			"detail_href": "/file/RKwgZb/info",
-			"id": "RKwgZb",
-			"file_name": "02 Hangar 18.mp3",
-			"description": "",
-			"date_created": 1513033304,
-			"date_last_view": 1513033304,
-			"list_description": ""
-		},
-		{
-			"detail_href": "/file/DRaL_e/info",
-			"id": "DRaL_e",
-			"file_name": "03 Take No Prisoners.mp3",
-			"description": "",
-			"date_created": 1513033304,
-			"date_last_view": 1513033304,
-			"list_description": ""
-		}
-	]
-}
-
-
HTTP 404: Not Found
-{
-	"success": false,
-	"value": "list_not_found",
-}
-
-
-
-{{end}} \ No newline at end of file diff --git a/res/template/fragments/api/list-post.html b/res/template/fragments/api/list.html similarity index 53% rename from res/template/fragments/api/list-post.html rename to res/template/fragments/api/list.html index f7df0d0..26e2410 100644 --- a/res/template/fragments/api/list-post.html +++ b/res/template/fragments/api/list.html @@ -4,7 +4,7 @@

Description

- Creates a list of files that can be viewed together on the file + Creates a list of files that can be viewed together on the file viewer page.

Parameters

@@ -81,4 +81,82 @@
-{{end}} \ No newline at end of file +{{end}} +{{define "api-list-get"}} +
+ GET/list/{id} +
+

Description

+

+ Returns information about a file list and the files in it. +

+

Parameters

+ + + + + + + + + + + + + +
ParamRequiredLocationDescription
idtrueURLID of the list
+

Returns

+

+ The API will return some basic information about every file. + Every file also has a "detail_href" field which contains a URL + to the info API of the file. Follow that link to get more + information about the file like size, checksum, mime type, etc. + The address is relative to the API URL and should be appended to + the end. +

+
HTTP 200: OK
+{
+	"success": true,
+	"id": "L8bhwx",
+	"title": "Rust in Peace",
+	"date_created": 1513033315,
+	"files": [
+		{
+			"detail_href": "/file/_SqVWi/info",
+			"id": "_SqVWi",
+			"file_name": "01 Holy Wars... The Punishment Due.mp3",
+			"description": "",
+			"date_created": 1513033304,
+			"date_last_view": 1513033304,
+			"list_description": ""
+		},
+		{
+			"detail_href": "/file/RKwgZb/info",
+			"id": "RKwgZb",
+			"file_name": "02 Hangar 18.mp3",
+			"description": "",
+			"date_created": 1513033304,
+			"date_last_view": 1513033304,
+			"list_description": ""
+		},
+		{
+			"detail_href": "/file/DRaL_e/info",
+			"id": "DRaL_e",
+			"file_name": "03 Take No Prisoners.mp3",
+			"description": "",
+			"date_created": 1513033304,
+			"date_last_view": 1513033304,
+			"list_description": ""
+		}
+	]
+}
+
+
HTTP 404: Not Found
+{
+	"success": false,
+	"value": "list_not_found",
+}
+
+
+
+{{end}}