v1 docs done for now

views/docs/v1.moon

@@ -88,16 +88,15 @@ class Docs_1 extends Widget
 
     button class: "collapsible", "Examples"
     div class: "content", ->
-      blockquote ->
+      p ->
         code "#{domain}/v1/get/12?api_key=#{example_key}"
-        p ->
+        text " (assuming a task with ID "
-          text "Assuming a task with ID "
+        code 12
-          code 12
+        text " belongs to you, and the "
-          text " belongs to you, and the "
+        code "api_key"
-          code "api_key"
+        text " is valid):"
-          text " is valid, returns:"
+        br!
-        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\"}}"
+        code title: "(This example is a real task that I added while developing this API. :P)", "{\"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"
@@ -112,15 +111,15 @@ class Docs_1 extends Widget
 
     button class: "collapsible", "Examples"
     div class: "content", ->
-      blockquote ->
+      p ->
-        p "As a header:"
+        text "As a header:"
+        br!
         code "Authorization: #{example_key}"
-        p ->
+      p ->
-          text "As part of a JSON object:"
+        text "As part of a JSON object: (POSTing to "
-          br!
+        code "#{domain}/v1/get"
-          text "(POSTing to "
+        text " in this example)"
-          code "#{domain}/v1/get"
+        br!
-          text " in this example)"
         code "{ \"id\": 12, \"api_key\": \"#{example_key}\" }"
 
     a class: ".top", href: "#top", "back to top"
@@ -150,7 +149,7 @@ class Docs_1 extends Widget
 
     a class: ".top", href: "#top", "back to top"
     a name: "task-operations"
-    h3 "/new, /get, /do, /undo, /edit, /delete"
+    h2 "/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 ->
@@ -177,18 +176,38 @@ class Docs_1 extends Widget
 
     button class: "collapsible", "Examples"
     div class: "content", ->
-      p "To be written."
+      p ->
-      -- TODO example using just query stuff, one w header and URL hierarchy params only
+        text "Authorization Header and URL parameter only:"
-      -- state every one returns the same thing except delete just returns success or errors
+        br!
+        text "Header: "
+        code "Authorization: #{example_key}"
+        br!
+        text "URL: "
+        code "#{domain}/v1/do/193"
+        br!
+        text "(Assuming everything is correct, would return a task, now marked done (regardless of previous value).)"
+
+      p ->
+        text "Using only query parameters (not a good idea!):"
+        br!
+        code "#{domain}/v1/get?api_key=#{example_key}&id=52"
+        br!
+        text "(Would return whatever task 52 is.. if it's yours. :P)"
+
+      p ->
+        text "Using JSON only:"
+        br!
+        code "{ \"api_key\": \"#{example_key}\", \"content\": \"I gotta do something..something useful!\" }"
+        br!
+        text "POSTed to: "
+        code "#{domain}/v1/new"
+        br!
+        text "(And of course, would return the new task.)"
 
     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"
@@ -219,15 +238,15 @@ class Docs_1 extends Widget
           td "'asc' (oldest first)"
 
     p ->
-      text "If you request a page beyond the number of pages available, the last page will be returned. "
+      text "If you request a page < 1, will return first page. Likewise, requesting a page beyond the number of pages available will return the last page. "
       code "page"
-      text " is specified in the response, so you will know if you have received a different page than requested. Additionally, "
+      text " is specified in each response, so you will know if you have received a different page than requested. Additionally, "
       code "pages"
-      text " is defined in all requests to "
+      text " is defined in all responses, telling you how many pages there are."
-      code "/list"
-      text ". Example response (with tasks trimmed out):"
 
-    blockquote ->
+    p ->
+      text "Here is an example response (with tasks omitted):"
+      br!
       code '{ "success": true, page: 5, pages: 10, tasks: [ /* task list omitted */ ] }'
 
     a class: ".top", href: "#top", "back to top"
@@ -247,28 +266,26 @@ class Docs_1 extends Widget
     a name: "new-key"
     h3 "/key/new"
 
-    p "Send an empty request. Receive the following:"
+    p ->
-
+      text "Send an empty request. Receive something like the following:"
-    blockquote ->
+      br!
-      code '{ "success": true, "api_key": { "id": 4, "user_id": 1, "key": "<key text omitted>", "created_at": "2018-04-25 06:05:53", "updated_at": "2018-04-25 06:05:53" } }'
+      code "{ \"success\": true, \"api_key\": { \"user_id\": 1, \"key\": \"#{example_key}\", \"created_at\": \"2018-04-25 06:05:53\", \"updated_at\": \"2018-04-25 06:05:53\" } }"
-
-    p "NOTE: For some reason, API key IDs are not being returned with API keys currently."
 
     a class: ".top", href: "#top", "back to top"
     a name: "delete-key"
-    h3 "/key/delete"
+    h3 "/key/delete/:key"
 
     p ->
       text "Send a POST request with "
       code "id"
       text " or "
       code "key"
-      text " defined to delete an API key. Note: You can delete the API key you are currently using with this endpoint, so be careful!"
+      text " defined to delete an API key. Returns just the "
-
-    p ->
-      text "Returns just the "
       code '{ "success": true }'
       text " JSON if successful."
+      br!
+      b "Note"
+      text ": You can delete the API key you are currently using with this endpoint, so be careful!"
 
     a class: ".top", href: "#top", "back to top"
     a name: "errors"
@@ -278,10 +295,10 @@ class Docs_1 extends Widget
 
     ul ->
       li "400: Bad Request. This means something on the client-side did not call the API correctly."
-      li "404: Not Found. This means the requested item doesn't exist."
+      li "404: Not Found. This means the requested item doesn't exist. (For example, getting a task that has been deleted.)"
       li "500: Internal Server Error. Something went wrong with the server while processing your request."
       li ->
-        text "501: Not Implemented. This error should only exist for the next few hours/days as I finish implementing "
+        text "501: Not Implemented. This error only exists for "
         code "/random"
         text ", the only part of the API not already implemented."
 
@@ -297,12 +314,30 @@ class Docs_1 extends Widget
     a name: "changes"
     h2 "Changes"
 
-    -- NOTE id stuff removed because never worked
+    p "Recent additions (v1.1 I guess):"
-    -- NOTE fixed large bug with several actions -> get, do, undo
+    ul ->
+      li ->
+        text "Fixed a bug with "
+        code "/get"
+        text ", "
+        code "/do"
+        text ", and "
+        code "/undo"
+        text " not returning tasks (just success boolean or errors)."
+      li ->
+        text "Added "
+        code "/edit"
+        text " endpoint for modifying tasks."
+      li ->
+        text "Removed "
+        code "id"
+        text " from API keys, as they weren't working anyhow, and aren't neccesary."
+      li "Added the ability to make requests using a URI and an authorization method only, which should make it easier to develop apps for. (More flexibility in how the API can be used.)"
+      li "Extensively rewrote the API documentation. *wipes sweat from brow*"
 
-    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 API versions will be supported indefinitely, unless a new feature requires a backwards-incompatible change to the database. In that case, an API will be marked deprecated and will remain available for at least 6 months."
 
-    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."
+    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 to the API itself are introduced."
 
     a class: ".top", href: "#top", "back to top"
     a name: "next"
@@ -315,11 +350,8 @@ class Docs_1 extends Widget
         text "Implementing "
         code "/random"
         text " endpoint."
-      li ->
+      li "Web interface utilizing edit endpoint for modifying tasks."
-        code "/edit"
+      li "Web interface using a paginated interface and sorting by incomplete tasks first."
-        text " endpoint for modifying the "
-        code "content"
-        text " of a task. The web interface will also be updated to utilize this."
       li ->
         code "/search"
         text " endpoint. The web interface will also be updated to utilize this."
@@ -327,14 +359,16 @@ class Docs_1 extends Widget
       li ->
         code "/duplicate"
         text " endpoint for duplicating a task or list (with optional inclusion of any sub-tasks/sub-lists). The web interface will be updated to utilize this."
+      li "Web interface will dynamically create lists if you try to go to a URL specifying a list that doesn't exist."
+      -- Note: Take parameter and slugify it, then create if it doesn't exist
+      li "Tasks will be able to have parent tasks as well as being on a list."
+      li "List option to only allow unique items on it."
+      li "List option to not allow deleting items from it."
       li "CLI program for interacting with the API."
-      li ->
-        span class: "error", "BUG"
-        text ": IDs are not returned with requests to "
-        code "/key/new"
-        text " endpoint."
       li "Twitter integration."
-      li "Data export. (Note: Initially will be a large JSON dump, but you can contact me if you have special needs for data export and I will develop these upon request.)"
+      li ->
+        text "Data export. (Note: Initially will be a large JSON dump, but you can contact me if you have special needs for data export and I will develop these upon request.)"
+        ul -> li "Will be API-based, with options for which tasks to include or exclude, defaulting to exporting everything."
 
     p "And this is a list of ideas that may or may not be coming a bit later on, still being thought about:"
 
@@ -343,7 +377,9 @@ class Docs_1 extends Widget
       li "Reminders."
       li "Recurring tasks."
       li "Shared tasks."
-      li "Customization of web interface. (e.g. select between current interface and a kanban-style board)"
+      li ->
+        text "Customization of web interface. (e.g. select between current interface and a kanban-style board)"
+        ul -> li "This may be implemented based on both a default setting and allowing each list to specify what interface it uses."
       li "Reordering tasks/lists. (This one requires some research on my part of how to implement this efficiently.)"
       li "Tagging system (for tasks/lists)."
       li "Due dates/times."