updating docs!

views/docs/v1.moon

@@ -1,34 +1,42 @@
 import Widget from require "lapis.html"
+import domain from require("lapis.config").get!
+
+if domain == "localhost"
+  domain = "http://localhost"
+else
+  domain = "https://#{domain}"
 
 class Docs_1 extends Widget
   content: =>
     task_list = ->
       ul ->
         li ->
-          a href: "#new", "/v1/new"
+          a href: "#new", "/new"
           text " { content: string }"
         li ->
-          a href: "#get", "/v1/get"
+          a href: "#get", "/get"
           text " { id: integer, content: string }"
         li ->
-          a href: "#do", "/v1/do"
+          a href: "#do", "/do"
           text " { id: integer, content: string }"
         li ->
-          a href: "#undo", "/v1/undo"
+          a href: "#undo", "/undo"
           text " { id: integer, content: string }"
         li ->
-          a href: "#delete", "/v1/delete"
+          a href: "#delete", "/delete"
           text " { id: integer, content: string }"
         li ->
-          a href: "#list", "/v1/list"
+          a href: "#list", "/list"
           text " { count: integer, done: boolean, page: integer, order: 'asc'/'desc' }"
         li ->
-          a href: "#random", "/v1/random"
+          a href: "#random", "/random"
           text " { count: integer, done: boolean }"
 
     style -> raw "h3 { font-family: monospace; }"
 
     ol style: "font-family: monospace;", ->
+      li ->
+        a href: "#endpoints", "Endpoints"
       li ->
         a href: "#auth", "Authorization"
       li ->
@@ -38,10 +46,35 @@ class Docs_1 extends Widget
         a href: "#keys", "API Keys"
         ul ->
           li ->
-            a href: "#new-key", "/v1/key/new"
+            a href: "#new-key", "/key/new"
           li ->
-            a href: "#delete-key", "/v1/key/delete"
+            a href: "#delete-key", "/key/delete"
             text " { id: integer, key: string }"
+      li ->
+        a href: "#errors", "Errors"
+      li ->
+        a href: "#rate-limit", "Rate Limiting"
+
+    a name: "endpoints"
+    h2 "Endpoints"
+
+    p ->
+      text "All endpoints are at "
+      code "#{config.domain}/v1"
+      text ", so for example, to get an existing task, send a POST request to "
+      code "#{config.domain}/v1/get"
+      text " with the appropriate JSON and authorization (listed below)."
+
+    p ->
+      text "All endpoints return a JSON object with a "
+      code "success"
+      text " boolean set to "
+      code "true"
+      text " and additional object data depending on the endpoint, or an "
+      code "errors"
+      text " array stating any errors in usage or encountered during processing. See "
+      a href: "#errors", "Errors"
+      text " below for more info on that."
 
     a name: "auth"
     h2 "Authorization"
@@ -70,15 +103,15 @@ class Docs_1 extends Widget
       text "Version 1 of this API is extremely simple. POST "
       code '{ "content": "this is a todo item" }'
       text " with valid authorization to "
-      code "/v1/new"
+      code "/new"
       text " to add tasks. The next four endpoints ("
-      code "/v1/get"
+      code "/get"
       text ","
-      code "/v1/do"
+      code "/do"
       text ","
-      code "/v1/undo"
+      code "/undo"
       text ","
-      code "/v1/delete"
+      code "/delete"
       text ") all use the same input to complete their operations (an "
       code "id"
       text " integer or "
@@ -86,59 +119,65 @@ class Docs_1 extends Widget
       text " boolean)."
 
     p ->
-      code "/v1/list"
+      code "/list"
       text " and "
-      code "/v1/random"
+      code "/random"
       text " are a little more complex, and explained further below."
 
     task_list!
 
     a name: "new"
-    h3 "/v1/new"
+    h3 "/new"
 
     p ->
-      text "As stated above, just POST a "
+      text "As stated above, to create a new task, just POST a "
       code "content"
-      text " string with valid authorization and a task item will be returned. Here's an example item:"
+      text " string with valid authorization and a new task item will be returned. Here's an example response:"
 
     blockquote ->
-      code '{ "id": 4, "user_id": 2, "content": "Get a new API key.", "done": false, "created_at": "", "updated_at": "" }'
+      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" } }'
 
-
-        -- "id", types.serial primary_key: true}
-        -- {"user_id", types.foreign_key}
-        -- {"content", types.text}
-        -- {"done", types.boolean default: false}
-        --
-        -- {"created_at", types.time}
-        -- {"updated_at", types.time}
+    p ->
+      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 "
+      code "/list"
+      text " or "
+      code "/random"
+      text "."
 
     a name: "get"
-    h3 "/v1/get"
+    h3 "/get"
 
     a name: "do"
-    h3 "/v1/do"
+    h3 "/do"
 
     a name: "undo"
-    h3 "/v1/undo"
+    h3 "/undo"
 
     a name: "delete"
-    h3 "/v1/delete"
+    h3 "/delete"
 
     a name: "list"
-    h3 "/v1/list"
+    h3 "/list"
 
     a name: "random"
-    h3 "/v1/random"
+    h3 "/random"
 
     a name: "keys"
     h2 "API Keys"
 
     a name: "new-key"
-    h3 "/v1/key/new"
+    h3 "/key/new"
 
     a name: "delete-key"
-    h3 "/v1/key/delete"
+    h3 "/key/delete"
+
+    a name: "errors"
+    h2 "Errors"
+
+    a name: "rate-limit"
+    h2 "Rate Limiting"
+
+    p "At this time there is no rate limiting. This will be developed when needed, and the API documentation updated to reflect that, with at least 2 months' warning."
 
 -- /list { count: #, done: bool, page: #, order: asc/desc } (if done not specified, returns all,
 --                        default count is 50, default page is 1, default order is latest first