From 0fc45304308219b4b2479106b4bbf08086edf4f0 Mon Sep 17 00:00:00 2001 From: Paul Liverman III Date: Tue, 24 Apr 2018 22:34:47 -0700 Subject: [PATCH] updating docs! --- views/docs/v1.moon | 111 ++++++++++++++++++++++++++++++--------------- 1 file changed, 75 insertions(+), 36 deletions(-) diff --git a/views/docs/v1.moon b/views/docs/v1.moon index 34071a6..c7fc347 100644 --- a/views/docs/v1.moon +++ b/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