lots of docs updates

views/docs/v1.moon

@@ -6,24 +6,29 @@ if domain == "localhost"
 else
   domain = "https://#{domain}"
 
+example_key = "JDJiJDEyJFRPaG0wOW16VXhoUTd3dElB"
+
 class Docs_1 extends Widget
   content: =>
     task_list = ->
-      ul ->
+      ul style: "font-family: monospace;", ->
         li ->
-          a href: "#new", "/new"
+          a href: "#task-operations", "/new/:content"
           text " { content: string }"
         li ->
-          a href: "#get", "/get"
+          a href: "#task-operations", "/get/:selector"
           text " { id: integer, content: string }"
         li ->
-          a href: "#do", "/do"
+          a href: "#task-operations", "/do/:selector"
           text " { id: integer, content: string }"
         li ->
-          a href: "#undo", "/undo"
+          a href: "#task-operations", "/undo/:selector"
           text " { id: integer, content: string }"
         li ->
-          a href: "#delete", "/delete"
+          a href: "#task-operations", "/edit/:selector"
+          text " { id: integer, content: string, new_content: string }"
+        li ->
+          a href: "#task-operations", "/delete/:selector"
           text " { id: integer, content: string }"
         li ->
           a href: "#list", "/list"
@@ -53,8 +58,8 @@ class Docs_1 extends Widget
           li ->
             a href: "#new-key", "/key/new"
           li ->
-            a href: "#delete-key", "/key/delete"
+            a href: "#delete-key", "/key/delete/:key"
-            text " { id: integer, key: string }"
+            text " { key: string }"
       li ->
         a href: "#errors", "Errors"
       li ->
@@ -63,154 +68,127 @@ class Docs_1 extends Widget
         a href: "#changes", "Changes"
       li ->
         a href: "#next", "Coming Next"
+      li ->
+        a href: "#notes", "Notes"
 
     a name: "endpoints"
     h2 "Endpoints"
 
     p ->
-      text "All endpoints are at "
+      text "All endpoints are under "
       code "#{domain}/v1"
-      text ", so for example, to get an existing task, send a POST request to "
+      text ", and accept parameters in the URL hierarchy, from POSTed JSON, in URI query string params, and for API keys, in an Authorization header. Most parameters are optional, with the only required parameters specified as part of the URL hierarchy."
-      code "#{domain}/v1/get"
-      text " with the appropriate JSON and authorization (listed below)."
 
     p ->
-      text "All endpoints return a JSON object with a "
+      text "All endpoints return HTTP status 200 when successful, as well as a JSON object ("
-      code "success"
+      code '{ "success": true }'
-      text " boolean set to "
+      text ") with a success boolean and extra data depending on the endpoint. When errors are encountered, a non-200 HTTP status code is sent, along with a JSON object ("
-      code "true"
+      code '{ "success": false, "errors": [ /*list of strings omitted*/ ] }'
-      text " and additional object data depending on the endpoint, or an "
+      text ") with an array of errors (usually containing a single error)."
-      code "errors"
+
-      text " array stating any errors in usage or encountered during processing. See "
+    button class: "collapsible", "Examples"
-      a href: "#errors", "Errors"
+    div class: "content", ->
-      text " below for more info on that."
+      blockquote ->
+        code "#{domain}/v1/get/12?api_key=#{example_key}"
+        p ->
+          text "Assuming a task with ID "
+          code 12
+          text " belongs to you, and the "
+          code "api_key"
+          text " is valid, returns:"
+        code "{\"success\":true,\"task\":{\"created_at\":\"2018-04-24 14:15:04\",\"id\":12,\"content\":\"Make index return a logged_out view instead of redirecting to login\",\"done\":true,\"user_id\":1,\"updated_at\":\"2018-04-25 04:28:36\"}}"
+        p "(Note: This example is a real task that I added while developing this API. :P)"
 
     a class: ".top", href: "#top", "back to top"
     a name: "auth"
     h2 "Authorization"
 
-    p "Authorization is done using a session cookie on the web interface, or an API key sent along with API requests."
+    p "Authorization is done by sending an API key along with other parameters. It can be sent as an Authorization header, in a URI query string (not recommended), or as part of a POSTed JSON object."
-    p ->
-      text "API keys can be sent in an Authorization header or as an "
-      code "api_key"
-      text " field in JSON."
-
-    blockquote ->
-      code "Authorization: JDJiJDEyJFRPaG0wOW16VXhoUTd3dElB"
-
-    blockquote ->
-      code '{ "api_key": "JDJiJDEyJFRPaG0wOW16VXhoUTd3dElB" }'
 
     p ->
       text "Grab an API key from "
       a href: @url_for("index"), "the web interface"
       text " to get started. You can also delete existing API keys there."
 
+    button class: "collapsible", "Examples"
+    div class: "content", ->
+      blockquote ->
+        p "As a header:"
+        code "Authorization: #{example_key}"
+        p ->
+          text "As part of a JSON object:"
+          br!
+          text "(POSTing to "
+          code "#{domain}/v1/get"
+          text " in this example)"
+        code "{ \"id\": 12, \"api_key\": \"#{example_key}\" }"
+
     a class: ".top", href: "#top", "back to top"
     a name: "tasks"
     h2 "Tasks"
 
     p ->
-      text "Version 1 of this API is extremely simple. POST "
+      text "In the endpoints listed below, "
-      code '{ "content": "this is a todo item" }'
+      code ":content"
-      text " with valid authorization to "
+      text " represents an optional URI-encoded string (for "
-      code "/new"
+      code "/new/:content"
-      text " to add tasks. The next four endpoints ("
+      text " only), and "
-      code "/get"
+      code ":selector"
-      text ","
+      text " represents an integer for selecting via ID, or a URI-encoded string for selecting via content (generally not recommended). All endpoints except "
-      code "/do"
+      code "/list"
-      text ","
+      text " and "
-      code "/undo"
+      code "/random"
-      text ","
+      text " accept these in the URL, as query parameters, or in a POSTed JSON object, and operate on a single task."
-      code "/delete"
-      text ") all use the same input to complete their operations (an "
-      code "id"
-      text " integer or "
-      code "content"
-      text " boolean)."
 
     p ->
       code "/list"
       text " and "
       code "/random"
-      text " are a little more complex, and explained further below."
+      text " are a little more complex, and are explained further below."
 
     task_list!
 
     a class: ".top", href: "#top", "back to top"
-    a name: "new"
+    a name: "task-operations"
-    h3 "/new"
+    h3 "/new, /get, /do, /undo, /edit, /delete"
+
+    p "As stated above, all of these operations accept the same data from the same formats, and return data in the same format, except:"
+    ul ->
+      li ->
+        code "/new"
+        text " only accepts "
+        code "content"
+        text " for input (you can't specify an ID for something that doesn't exist..)"
+      li ->
+        code "/edit"
+        text " additionally accepts a "
+        code "done"
+        text " boolean, and/or "
+        code "new_content"
+        text " specifying how to modify a task."
+      li ->
+        code "/delete"
+        text " only returns a success boolean (and errors array if there are errors)."
 
     p ->
-      text "As stated above, to create a new task, just POST a "
+      text "All tasks are returned like so:"
-      code "content"
+      br!
-      text " string with valid authorization and a new task item will be returned. Here's an example response:"
-
-    blockquote ->
       code '{ "success": true, "task": { "id": 4, "user_id": 2, "content": "Get a new API key.", "done": false, "created_at": "2018-04-25 04:27:47", "updated_at": "2018-04-25 04:27:47" } }'
 
-    p ->
+    button class: "collapsible", "Examples"
-      text "This same format is used to return any task, whether it is as a response to these simple queries, or as part of an array returned by "
+    div class: "content", ->
-      code "/list"
+      p "To be written."
-      text " or "
+      -- TODO example using just query stuff, one w header and URL hierarchy params only
-      code "/random"
+      -- state every one returns the same thing except delete just returns success or errors
-      text "."
-
-    a class: ".top", href: "#top", "back to top"
-    a name: "get"
-    h3 "/get"
-
-    p ->
-      text "Select a task by its "
-      code "id"
-      text " (an integer), or its "
-      code "content"
-      text " (a string). Example request:"
-
-    blockquote ->
-      code '{ "id": 5 }'
-
-    p ->
-      text "See "
-      a href: "#new", "/new"
-      text " for an example response."
-
-    a class: ".top", href: "#top", "back to top"
-    a name: "do"
-    h3 "/do"
-
-    p "Marks a task as done. Returns success even if the task was already marked done. Example request:"
-
-    blockquote ->
-      code '{ "content": "that one thing you need to remember to do" }'
-
-    p ->
-      text "See "
-      a href: "#new", "/new"
-      text " for an example response."
-
-    a class: ".top", href: "#top", "back to top"
-    a name: "undo"
-    h3 "/undo"
-
-    p ->
-      text "Marks a task as not done. Returns success even if the task was already marked not done. See "
-      a href: "#new", "/new"
-      text " for an example response."
-
-    a class: ".top", href: "#top", "back to top"
-    a name: "delete"
-    h3 "/delete"
-
-    p ->
-      text "Deletes a task. Just returns "
-      code '{ "success": true }'
-      text " if successful."
 
     a class: ".top", href: "#top", "back to top"
     a name: "list"
     h3 "/list"
 
+    p "Note: The API was recently updated (as evidenced by all the changes here), however, for the moment, this is where I have stopped updating documentation."
+
+    p "Below here, the important things to note are that API keys no longer have IDs (that seemed to be broken anyhow), and that random is still not implemented."
+
     p ->
       text "Returns an array of task objects (see "
       a href: "#new", "/new"
@@ -319,6 +297,9 @@ class Docs_1 extends Widget
     a name: "changes"
     h2 "Changes"
 
+    -- NOTE id stuff removed because never worked
+    -- NOTE fixed large bug with several actions -> get, do, undo
+
     p "I intend to keep support for v1 of the API indefinitely. If new features require backwards-incompatible API changes, those will be released under a new version of the API, and v1 will remain accessible for at least 6 months before switching."
 
     p "All new features that do not require modifications to existing API calls will be added to v1 as they are introduced. The next version of the API will only exist if backwards-incompatible changes are introduced."
@@ -378,3 +359,13 @@ class Docs_1 extends Widget
       li "A page for accepting payments. At this stage, this is optional and I will be relying purely on people wanting to see this system succeed. In the future, more advanced API features may be behind a subscription model (intended to be $1.50/year)."
 
     a class: ".top", href: "#top", "back to top"
+    a name: "notes"
+    h2 "Notes"
+
+    p "All routes are technically available by any HTTP verb. However, depending on the HTTP spec for the verb you use, this may cause required data to not be parsed correctly."
+
+    p "I would recommend sticking to POST requests, but GET works for sure, and /new might work with anything if the content is specified in the URL." -- TODO clean up format here
+
+    p "Do not write your code expecting ONLY the data specified here, as more features are added, more data will be in the task objects returned."
+
+    a class: ".top", href: "#top", "back to top"