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

v1 docs done for now

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

156
views/docs/v1.moon
View File

@ -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 "
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)"
text " (assuming a task with ID "
code 12
text " belongs to you, and the "
code "api_key"
text " is valid):"
br!
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\"}}"
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 "As a header:"
p ->
text "As a header:"
br!
code "Authorization: #{example_key}"
p ->
text "As part of a JSON object:"
br!
text "(POSTing to "
code "#{domain}/v1/get"
text " in this example)"
p ->
text "As part of a JSON object: (POSTing to "
code "#{domain}/v1/get"
text " in this example)"
br!
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."
-- 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
p ->
text "Authorization Header and URL parameter only:"
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 "
code "/list"
text ". Example response (with tasks trimmed out):"
text " is defined in all responses, telling you how many pages there are."
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:"
blockquote ->
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" } }'
p "NOTE: For some reason, API key IDs are not being returned with API keys currently."
p ->
text "Send an empty request. Receive something like the following:"
br!
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\" } }"
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!"
p ->
text "Returns just the "
text " defined to delete an API key. 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
-- NOTE fixed large bug with several actions -> get, do, undo
p "Recent additions (v1.1 I guess):"
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 ->
code "/edit"
text " endpoint for modifying the "
code "content"
text " of a task. The web interface will also be updated to utilize this."
li "Web interface utilizing edit endpoint for modifying tasks."
li "Web interface using a paginated interface and sorting by incomplete tasks first."
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."