simplex/views/docs/v1.moon

import Widget from require "lapis.html"

class Docs_1 extends Widget
  content: =>
    task_list = ->
      ul ->
        li ->
          a href: "#new", "/v1/new"
          text " { content: string }"
        li ->
          a href: "#get", "/v1/get"
          text " { id: integer, content: string }"
        li ->
          a href: "#do", "/v1/do"
          text " { id: integer, content: string }"
        li ->
          a href: "#undo", "/v1/undo"
          text " { id: integer, content: string }"
        li ->
          a href: "#delete", "/v1/delete"
          text " { id: integer, content: string }"
        li ->
          a href: "#list", "/v1/list"
          text " { count: integer, done: boolean, page: integer, order: 'asc'/'desc' }"
        li ->
          a href: "#random", "/v1/random"
          text " { count: integer, done: boolean }"

    style -> raw "h3 { font-family: monospace; }"

    ol style: "font-family: monospace;", ->
      li ->
        a href: "#auth", "Authorization"
      li ->
        a href: "#tasks", "Tasks"
        task_list!
      li ->
        a href: "#keys", "API Keys"
        ul ->
          li ->
            a href: "#new-key", "/v1/key/new"
          li ->
            a href: "#delete-key", "/v1/key/delete"
            text " { id: integer, key: string }"

    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 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 "/v1/new"
      text " to add tasks. The next four endpoints ("
      code "/v1/get"
      text ","
      code "/v1/do"
      text ","
      code "/v1/undo"
      text ","
      code "/v1/delete"
      text ") all use the same input to complete their operations (an "
      code "id"
      text " integer or "
      code "content"
      text " boolean)."

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

    task_list!

    a name: "new"
    h3 "/v1/new"

    p ->
      text "As stated above, just POST a "
      code "content"
      text " string with valid authorization and a task item will be returned. Here's an example item:"

    blockquote ->
      code '{ "id": 4, "user_id": 2, "content": "Get a new API key.", "done": false, "created_at": "", "updated_at": "" }'


        -- "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}

    a name: "get"
    h3 "/v1/get"

    a name: "do"
    h3 "/v1/do"

    a name: "undo"
    h3 "/v1/undo"

    a name: "delete"
    h3 "/v1/delete"

    a name: "list"
    h3 "/v1/list"

    a name: "random"
    h3 "/v1/random"

    a name: "keys"
    h2 "API Keys"

    a name: "new-key"
    h3 "/v1/key/new"

    a name: "delete-key"
    h3 "/v1/key/delete"

-- /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
-- also returns page: #, pages: #, tasks: []
-- /random { count: #, done: bool } (both args optional, defaults count 1, done false)