add api documentation for directory api

res/template/fragments/api/list.html

@@ -0,0 +1,162 @@
+{{define "api-list-post"}}
+<details class="api_doc_details request_post">
+	<summary><span class="method">POST</span>/list</summary>
+	<div>
+		<h3>Description</h3>
+		<p>
+			Creates a list of files that can be viewed together on the file
+			viewer page.
+		</p>
+		<h3>Parameters</h3>
+		<p>
+			POST body should be a JSON object, example below. A list can contain
+			maximally 10000 files. If you try to add more the request will fail.
+		</p>
+		<h4>Example</h4>
+<pre>
+{
+	"title": "My beautiful photos",
+	"description": "An album of photos from my vacation in Austria",
+	"files": [ // Ordered array of files to add to the list
+		{
+			"id": "abc123",
+			"description": "First photo of the week, such a beautiful valley"
+		},
+		{
+			"id": "123abc",
+			"description": "The week went by so quickly, here's a photo from the plane back"
+		}
+	]
+}
+</pre>
+		<h3>Returns</h3>
+<pre>HTTP 200: OK
+{
+	"success": true,
+	"id": "yay137" // ID of the newly created list
+}
+</pre>
+<pre>HTTP 422: Unprocessable Entity
+{
+	"success": false,
+	"value": "file_not_found",
+	"id": "Oh42No", // The file you tried to add with this ID does not exist
+	"message": "File Oh42No was not found in the database."
+}
+</pre>
+<pre>HTTP 413: Payload too large
+{
+	"success": false,
+	"value": "too_many_files",
+	"message": "This list contains too many files, max 10000 allowed."
+}
+</pre>
+<pre>HTTP 422: Unprocessable Entity
+{
+	"success": false,
+	"value": "json_parse_failed",
+	"message": "The JSON object in the request body could not be read."
+}
+</pre>
+<pre>HTTP 413: Payload too large
+{
+	"success": false,
+	"value": "title_too_long",
+	"message": "The title of this list is too long, max 300 characters allowed."
+}
+</pre>
+<pre>HTTP 413: Payload too large
+{
+	"success": false,
+	"value": "description_too_long",
+	"message": "The description of this list or one of the files in the list is too long, max 3000 characters allowed."
+}
+</pre>
+<pre>HTTP 422: Unprocessable Entity
+{
+	"success": false,
+	"value": "cannot_create_empty_list",
+	"message": "You cannot make a list with no files."
+}
+</pre>
+	</div>
+</details>
+{{end}}
+{{define "api-list-get"}}
+<details class="api_doc_details request_get">
+	<summary><span class="method">GET</span>/list/{id}</summary>
+	<div>
+		<h3>Description</h3>
+		<p>
+			Returns information about a file list and the files in it.
+		</p>
+		<h3>Parameters</h3>
+		<table>
+			<tr>
+				<td>Param</td>
+				<td>Required</td>
+				<td>Location</td>
+				<td>Description</td>
+			</tr>
+			<tr>
+				<td>id</td>
+				<td>true</td>
+				<td>URL</td>
+				<td>ID of the list</td>
+			</tr>
+		</table>
+		<h3>Returns</h3>
+			<p>
+				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.
+			</p>
+<pre>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": ""
+		}
+	]
+}
+</pre>
+<pre>HTTP 404: Not Found
+{
+	"success": false,
+	"value": "list_not_found",
+}
+</pre>
+</div>
+</details>
+{{end}}