274 lines
7.4 KiB
Plaintext
274 lines
7.4 KiB
Plaintext
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", "/new"
|
|
text " { content: string }"
|
|
li ->
|
|
a href: "#get", "/get"
|
|
text " { id: integer, content: string }"
|
|
li ->
|
|
a href: "#do", "/do"
|
|
text " { id: integer, content: string }"
|
|
li ->
|
|
a href: "#undo", "/undo"
|
|
text " { id: integer, content: string }"
|
|
li ->
|
|
a href: "#delete", "/delete"
|
|
text " { id: integer, content: string }"
|
|
li ->
|
|
a href: "#list", "/list"
|
|
text " { count: integer, done: boolean, page: integer, order: 'asc'/'desc' }"
|
|
li ->
|
|
a href: "#random", "/random"
|
|
text " { count: integer, done: boolean }"
|
|
|
|
style -> raw "h3 { font-family: monospace; }"
|
|
|
|
a name: "top"
|
|
ol style: "font-family: monospace;", ->
|
|
li ->
|
|
a href: "#endpoints", "Endpoints"
|
|
li ->
|
|
a href: "#auth", "Authorization"
|
|
li ->
|
|
a href: "#tasks", "Tasks"
|
|
task_list!
|
|
li ->
|
|
a href: "#keys", "API Keys"
|
|
ul ->
|
|
li ->
|
|
a href: "#new-key", "/key/new"
|
|
li ->
|
|
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 "#{domain}/v1"
|
|
text ", so for example, to get an existing task, send a POST request to "
|
|
code "#{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 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 ->
|
|
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."
|
|
|
|
a href: "#top", "back to top"
|
|
a name: "tasks"
|
|
h2 "Tasks"
|
|
|
|
p ->
|
|
text "Version 1 of this API is extremely simple. POST "
|
|
code '{ "content": "this is a todo item" }'
|
|
text " with valid authorization to "
|
|
code "/new"
|
|
text " to add tasks. The next four endpoints ("
|
|
code "/get"
|
|
text ","
|
|
code "/do"
|
|
text ","
|
|
code "/undo"
|
|
text ","
|
|
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."
|
|
|
|
task_list!
|
|
|
|
a href: "#top", "back to top"
|
|
a name: "new"
|
|
h3 "/new"
|
|
|
|
p ->
|
|
text "As stated above, to create a new task, just POST a "
|
|
code "content"
|
|
text " string with valid authorization and a new task item will be returned. Here's an example response:"
|
|
|
|
blockquote ->
|
|
code style: "white-space: normal;", '{ "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 ->
|
|
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 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 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 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 href: "#top", "back to top"
|
|
a name: "delete"
|
|
h3 "/delete"
|
|
|
|
p ->
|
|
text "Deletes a task. Just returns "
|
|
code '{ "success": true }'
|
|
text " if successful."
|
|
|
|
a href: "#top", "back to top"
|
|
a name: "list"
|
|
h3 "/list"
|
|
|
|
p ->
|
|
text "Returns an array of task objects (see "
|
|
a href: "#new", "/new"
|
|
text " for an example task object). All arguments are optional:"
|
|
|
|
element "table", ->
|
|
thead ->
|
|
tr ->
|
|
th "Argument"
|
|
th "Type"
|
|
th "Default"
|
|
tbody ->
|
|
tr ->
|
|
td -> code "count"
|
|
td "integer"
|
|
td 50
|
|
tr ->
|
|
td -> code "done"
|
|
td "boolean"
|
|
td "returns ALL tasks if not set"
|
|
tr ->
|
|
td -> code "page"
|
|
td "integer"
|
|
td 1
|
|
tr ->
|
|
td -> code "order"
|
|
td "'asc'/'desc'"
|
|
td "'asc' (oldest first)"
|
|
|
|
p ->
|
|
text "If you request a page beyond the number of pages available, the last page will be returned. "
|
|
code "page"
|
|
text " is specified in the response, so you will know if you have received a different page than requested. Additionally, "
|
|
code "pages"
|
|
text " is defined in all requests to "
|
|
code "/list"
|
|
text ". Example response (with tasks trimmed out):"
|
|
|
|
blockquote ->
|
|
code '{ "success": true, page: 5, pages: 10, tasks: [ /* task list omitted */ ] }'
|
|
|
|
a href: "#top", "back to top"
|
|
a name: "random"
|
|
h3 "/random"
|
|
|
|
a href: "#top", "back to top"
|
|
a name: "keys"
|
|
h2 "API Keys"
|
|
|
|
a href: "#top", "back to top"
|
|
a name: "new-key"
|
|
h3 "/key/new"
|
|
|
|
a href: "#top", "back to top"
|
|
a name: "delete-key"
|
|
h3 "/key/delete"
|
|
|
|
a href: "#top", "back to top"
|
|
a name: "errors"
|
|
h2 "Errors"
|
|
|
|
a href: "#top", "back to top"
|
|
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."
|
|
|
|
-- /random { count: #, done: bool } (both args optional, defaults count 1, done false)
|