diff --git a/editions/tw5.com/tiddlers/webserver/TiddlyWeb JSON tiddler format.tid b/editions/tw5.com/tiddlers/webserver/TiddlyWeb JSON tiddler format.tid new file mode 100644 index 000000000..cbd218674 --- /dev/null +++ b/editions/tw5.com/tiddlers/webserver/TiddlyWeb JSON tiddler format.tid @@ -0,0 +1,33 @@ +created: 20181002130513206 +modified: 20181002131123893 +tags: [[WebServer Guides]] +title: TiddlyWeb JSON tiddler format +type: text/vnd.tiddlywiki + +The web server API uses tiddlers in a special format originally designed for TiddlyWeb: + +* Field values are represented as strings. Lists (like the ''tags'' and ''list'' fields) use double square brackets to quote values that contain spaces +* Tiddlers are represented as an object containing any of a fixed set of standard fields, with custom fields being relegated to a special property called ''fields'' +* The standard fields are: ''bag'', ''created'', ''creator'', ''modified'', ''modifier'', ''permissions'', ''recipe'', ''revision'', ''tags'', ''text'', ''title'', ''type'', ''uri'' + +For example, consider the following tiddler: + +``` +{ + "title": "HelloThere", + "tags": "FirstTag [[Second Tag]]", + "my-custom-field": "Field value" +} +``` + +In transit over the API, the tiddler would be converted to the following format: + +``` +{ + "title": "HelloThere", + "tags": "FirstTag [[Second Tag]]", + "fields": { + "my-custom-field": "Field value" + } +} +``` diff --git a/editions/tw5.com/tiddlers/webserver/WebServer Routing.tid b/editions/tw5.com/tiddlers/webserver/WebServer API.tid similarity index 56% rename from editions/tw5.com/tiddlers/webserver/WebServer Routing.tid rename to editions/tw5.com/tiddlers/webserver/WebServer API.tid index 8364ec379..cd937537a 100644 --- a/editions/tw5.com/tiddlers/webserver/WebServer Routing.tid +++ b/editions/tw5.com/tiddlers/webserver/WebServer API.tid @@ -1,6 +1,6 @@ created: 20180630194032981 -modified: 20180630194042074 +modified: 20181002103516011 tags: WebServer -title: WebServer Routing +title: WebServer API type: text/vnd.tiddlywiki diff --git a/editions/tw5.com/tiddlers/webserver/WebServer API_ Delete Tiddler.tid b/editions/tw5.com/tiddlers/webserver/WebServer API_ Delete Tiddler.tid new file mode 100644 index 000000000..962d74902 --- /dev/null +++ b/editions/tw5.com/tiddlers/webserver/WebServer API_ Delete Tiddler.tid @@ -0,0 +1,19 @@ +created: 20181002112106875 +modified: 20181002124355314 +tags: [[WebServer API]] +title: WebServer API: Delete Tiddler +type: text/vnd.tiddlywiki + +Delete a tiddler + +``` +DELETE /bags/default/tiddlers/{title} +``` + +Parameters: + +* ''title'' - URI encoded title of the tiddler to delete + +Response: + +* 204 No Content \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/webserver/WebServer API_ Force Basic Authentication Login.tid b/editions/tw5.com/tiddlers/webserver/WebServer API_ Force Basic Authentication Login.tid new file mode 100644 index 000000000..356213ac8 --- /dev/null +++ b/editions/tw5.com/tiddlers/webserver/WebServer API_ Force Basic Authentication Login.tid @@ -0,0 +1,25 @@ +created: 20181002124825195 +modified: 20181002125214104 +tags: [[WebServer API]] +title: WebServer API: Force Basic Authentication Login +type: text/vnd.tiddlywiki + +Forces the server to request basic authentication login, and then redirects to the root + +``` +GET /login-basic +``` + +Requests an basic authentication from the browser, and redirects to the root if successful. + +Parameters: + +* none + +Response: + +* 302 Found +*> `Location: /` +* 401 Unauthorized +*> `WWW-Authenticate: Basic realm="Please provide your username and password to login to " + diff --git a/editions/tw5.com/tiddlers/webserver/WebServer API_ Get All Tiddlers.tid b/editions/tw5.com/tiddlers/webserver/WebServer API_ Get All Tiddlers.tid new file mode 100644 index 000000000..da58738b2 --- /dev/null +++ b/editions/tw5.com/tiddlers/webserver/WebServer API_ Get All Tiddlers.tid @@ -0,0 +1,22 @@ +created: 20181002131215403 +modified: 20181002131322026 +tags: [[WebServer API]] +title: WebServer API: Get All Tiddlers +type: text/vnd.tiddlywiki + +Gets an array of all raw tiddlers, excluding the ''text'' field. + +``` +GET /recipes/default/tiddlers/tiddlers.json +``` + +Parameters: + +* none + +Response: + + +* 200 OK +*> `Content-Type: application/json` +*> Body: array of tiddlers in [[TiddlyWeb JSON tiddler format]] diff --git a/editions/tw5.com/tiddlers/webserver/WebServer API_ Get Favicon.tid b/editions/tw5.com/tiddlers/webserver/WebServer API_ Get Favicon.tid new file mode 100644 index 000000000..6fe8ff6c6 --- /dev/null +++ b/editions/tw5.com/tiddlers/webserver/WebServer API_ Get Favicon.tid @@ -0,0 +1,21 @@ +created: 20181002123308575 +modified: 20181002124103586 +tags: [[WebServer API]] +title: WebServer API: Get Favicon +type: text/vnd.tiddlywiki + +Get the favicon for the wiki from the tiddler $:/favicon.ico + +``` +GET /favicon.ico +``` + +Parameters: + +* none + +Response: + +* 200 OK +*> `Content-Type: image/x-icon` +*> Body: image data from the tiddler $:/favicon.ico \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/webserver/WebServer API_ Get File.tid b/editions/tw5.com/tiddlers/webserver/WebServer API_ Get File.tid new file mode 100644 index 000000000..cebac2501 --- /dev/null +++ b/editions/tw5.com/tiddlers/webserver/WebServer API_ Get File.tid @@ -0,0 +1,25 @@ +created: 20181002123907518 +modified: 20181002124345482 +tags: [[WebServer API]] +title: WebServer API: Get File +type: text/vnd.tiddlywiki + +Get the content of a static file. See +[[using the integrated static file server|Using the integrated static file server]] + +``` +GET /files/ +``` + +Parameters: + +* ''pathname'' - URI encoded path to the file + +Response: + +* 200 OK +*> `Content-Type: ` (determined from file extension) +*> Body: data retrieved from file +* 403 Forbidden +* 404 Not Found + diff --git a/editions/tw5.com/tiddlers/webserver/WebServer API_ Get Server Status.tid b/editions/tw5.com/tiddlers/webserver/WebServer API_ Get Server Status.tid new file mode 100644 index 000000000..6bcd1e4ac --- /dev/null +++ b/editions/tw5.com/tiddlers/webserver/WebServer API_ Get Server Status.tid @@ -0,0 +1,43 @@ +created: 20181002125229601 +modified: 20181002125840235 +tags: [[WebServer API]] +title: WebServer API: Get Server Status +type: text/vnd.tiddlywiki + +Get server status information + +``` +GET /status +``` + +Parameters: + +* none + +Response: + +* 200 OK +*> `Content-Type: application/json` +*> Body: see below + +The JSON data returned comprises the following properties: + +* ''username'' - the username of the currently authenticated user. If undefined, the [[WebServer Parameter: anon-username]] is returned instead +* ''anonymous'' - true if the current user is anonymous +* ''read_only'' - true if the current user is restricted to read only access to the server +* ''space'' - always contains the object `{recipe: "default"}` +* ''tiddlywiki_version'' - the current TiddlyWiki version + +For example: + +``` +{ + "username": "", + "anonymous": true, + "read_only": false, + "space": { + "recipe": "default" + }, + "tiddlywiki_version": "5.1.18" +} +``` diff --git a/editions/tw5.com/tiddlers/webserver/WebServer API_ Get Tiddler Rendering.tid b/editions/tw5.com/tiddlers/webserver/WebServer API_ Get Tiddler Rendering.tid new file mode 100644 index 000000000..5fb75e76a --- /dev/null +++ b/editions/tw5.com/tiddlers/webserver/WebServer API_ Get Tiddler Rendering.tid @@ -0,0 +1,23 @@ +created: 20181002125954409 +modified: 20181002130237725 +tags: [[WebServer API]] +title: WebServer API: Get Tiddler Rendering +type: text/vnd.tiddlywiki + +Gets a rendering of the specified tiddler. See [[using the read-only single tiddler view|Using the read-only single tiddler view]] for more details. + +``` +GET /{title} +``` + +Parameters: + +* ''title'' - URI encoded title of the tiddler to render + +Response: + + +* 200 OK +*> `Content-Type: ` +*> Body: tiddler rendering +* 404 Not Found diff --git a/editions/tw5.com/tiddlers/webserver/WebServer API_ Get Tiddler.tid b/editions/tw5.com/tiddlers/webserver/WebServer API_ Get Tiddler.tid new file mode 100644 index 000000000..f9889f23f --- /dev/null +++ b/editions/tw5.com/tiddlers/webserver/WebServer API_ Get Tiddler.tid @@ -0,0 +1,23 @@ +created: 20181002130310180 +modified: 20181002130457330 +tags: [[WebServer API]] +title: WebServer API: Get Tiddler +type: text/vnd.tiddlywiki + +Gets the raw fields of a tiddler + +``` +GET /recipes/default/tiddlers/{title} +``` + +Parameters: + +* ''title'' - URI encoded title of the tiddler to retrieve + +Response: + + +* 200 OK +*> `Content-Type: application/json` +*> Body: tiddler in [[TiddlyWeb JSON tiddler format]] +* 404 Not Found diff --git a/editions/tw5.com/tiddlers/webserver/WebServer API_ Get Wiki.tid b/editions/tw5.com/tiddlers/webserver/WebServer API_ Get Wiki.tid new file mode 100644 index 000000000..7e208d478 --- /dev/null +++ b/editions/tw5.com/tiddlers/webserver/WebServer API_ Get Wiki.tid @@ -0,0 +1,23 @@ +created: 20181002124430552 +modified: 20181002124755134 +tags: [[WebServer API]] +title: WebServer API: Get Wiki +type: text/vnd.tiddlywiki + +Get the main wiki + +``` +GET / +``` + +The wiki is composed by rendering the tiddler identified in the [[root-tiddler|WebServer Parameter: root-tiddler]] parameter with the render type in the [[root-render-type|WebServer Parameter: root-render-type]] parameter. This is then served with the content type from the [[root-serve-type|WebServer Parameter: root-serve-type]] parameter. + +Parameters: + +* none + +Response: + +* 200 OK +*> `Content-Type: text/html` +*> Body: data retrieved from file diff --git a/editions/tw5.com/tiddlers/webserver/WebServer API_ Put Tiddler.tid b/editions/tw5.com/tiddlers/webserver/WebServer API_ Put Tiddler.tid new file mode 100644 index 000000000..8bdedcf3b --- /dev/null +++ b/editions/tw5.com/tiddlers/webserver/WebServer API_ Put Tiddler.tid @@ -0,0 +1,23 @@ +created: 20181002131341062 +modified: 20181002131556452 +tags: [[WebServer API]] +title: WebServer API: Put Tiddler +type: text/vnd.tiddlywiki + +Saves the raw fields of a tiddler + +``` +PUT /recipes/default/tiddlers/{title} +``` + +The body should be in [[TiddlyWeb JSON tiddler format]]. + +Parameters: + +* ''title'' - URI encoded title of the tiddler to save + +Response: + +* 204 No Content +*> `Content-Type: text/plain` +*> `Etag: "default//<changecount>:"` diff --git a/editions/tw5.com/tiddlers/webserver/WebServer.tid b/editions/tw5.com/tiddlers/webserver/WebServer.tid index f32113630..031dfefb1 100644 --- a/editions/tw5.com/tiddlers/webserver/WebServer.tid +++ b/editions/tw5.com/tiddlers/webserver/WebServer.tid @@ -1,5 +1,5 @@ created: 20180626150526207 -modified: 20180703095555387 +modified: 20181002103605866 tags: ListenCommand ServerCommand Features title: WebServer type: text/vnd.tiddlywiki @@ -14,7 +14,7 @@ The web server listens for requests coming over the network, and performs the fo * [[Authentication|WebServer Authentication]] is the process of identifying the current user. TiddlyWiki supports three types of authentication: [[Anonymous|WebServer Anonymous Access]], [[Basic|WebServer Basic Authentication]] and [[Header|WebServer Header Authentication]] * [[Authorization|WebServer Authorization]] is the process of determining which resources may be accessed by a particular user. TiddlyWiki implements a simple scheme whereby read and write access to the wiki can be independently controlled. -* [[Routing|WebServer Routing]] is the process of acting on the request, and returning any required data. +* Routing is the process of dispatching the request to the [[API handler|WebServer API]], and returning any required data. ! Usage