tmp/simplex
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

lots of docs updates

Browse Source
This commit is contained in:
Paul Liverman III 2018-05-01 18:00:43 -07:00
parent ddf8830c2c
commit 7ab94aacef
1 changed files with 105 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

219
views/docs/v1.moon
View File

@ -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"
text " { id: integer, key: string }"
a href: "#delete-key", "/key/delete/:key"
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 "
code "#{domain}/v1/get"
text " with the appropriate JSON and authorization (listed below)."
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."
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."
text "All endpoints return HTTP status 200 when successful, as well as a JSON object ("
code '{ "success": true }'
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 '{ "success": false, "errors": [ /*list of strings omitted*/ ] }'
text ") with an array of errors (usually containing a single error)."
button class: "collapsible", "Examples"
div class: "content", ->
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 ->
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 "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 "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 "
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)."
text "In the endpoints listed below, "
code ":content"
text " represents an optional URI-encoded string (for "
code "/new/:content"
text " only), and "
code ":selector"
text " represents an integer for selecting via ID, or a URI-encoded string for selecting via content (generally not recommended). All endpoints except "
code "/list"
text " and "
code "/random"
text " accept these in the URL, as query parameters, or in a POSTed JSON object, and operate on a single task."
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"
h3 "/new"
a name: "task-operations"
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 "
code "content"
text " string with valid authorization and a new task item will be returned. Here's an example response:"
blockquote ->
text "All tasks are returned like so:"
br!
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 ->
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 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."
button class: "collapsible", "Examples"
div class: "content", ->
p "To be written."
-- TODO example using just query stuff, one w header and URL hierarchy params only
-- state every one returns the same thing except delete just returns success or errors
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"