simplex/views/docs/v1.moon

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; }
      .top { font-size: 1.33rem; }
      blockquote > code { white-space: normal; }
    "

    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 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 ->
      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 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)."

    p ->
      code "/list"
      text " and "
      code "/random"
      text " are a little more complex, and explained further below."

    task_list!

    a class: ".top", 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 '{ "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."

    a class: ".top", 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 class: ".top", href: "#top", "back to top"
    a name: "random"
    h3 "/random"

    p "This is the only endpoint not currently implemented. This documentation will be updated once it is finished."
    -- TODO /random { count: #, done: bool } (both args optional, defaults count 1, done false)

    a class: ".top", href: "#top", "back to top"
    a name: "keys"
    h2 "API Keys"

    p "The API can be used to request new API keys and delete API keys, but cannot be used to look up API keys, or perform any other actions with API keys."

    a class: ".top", href: "#top", "back to top"
    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."

    a class: ".top", href: "#top", "back to top"
    a name: "delete-key"
    h3 "/key/delete"

    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 "
      code '{ "success": true }'
      text " JSON if successful."

    a class: ".top", href: "#top", "back to top"
    a name: "errors"
    h2 "Errors"

    p "In addition to an array of errors (usually only consisting of one error message), the HTTP status returned will indicate errors:"

    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 "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 "
        code "/random"
        text ", the only part of the API not already implemented."

    p "Right now, please report any 500 errors you encounter. In the future, these will be logged automatically."

    a class: ".top", 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."

    a class: ".top", href: "#top", "back to top"