paths:
  get:
    tags:
    - who
    summary: "Get an entity. If ?id not provided, see TRACE. ?sort and ?order apply to connections."
    parameters:
    - $ref: "#/components/parameters/id"
    - $ref: "#/components/parameters/namespace"
    - $ref: "#/components/parameters/light"
    - $ref: "#/components/parameters/md"
    - $ref: "#/components/parameters/sort"
    - $ref: "#/components/parameters/order"
    responses:
      200:
        $ref: "#/components/schemas/200"

  trace:
    deprecated: true
    tags:
    - who
    summary: "List all entities"
    parameters:
    - $ref: "#/components/parameters/namespace"
    - $ref: "#/components/parameters/sort"
    - $ref: "#/components/parameters/order"
    responses:
      200:
        content:
          application/json:
            schema:
              title: "Results"
              type: array
              items:
                type: string

  post:
    tags:
    - who
    summary: "Create a new entity"
    parameters:
    - $ref: "#/components/parameters/id"
    - $ref: "#/components/parameters/namespace"
    requestBody:
      description: "An entity where all fields are optional and modified is disallowed"
      content:
        $ref: "#/components/schemas/oneContent"
    responses:
      200:
        $ref: "#/components/schemas/200"

  put:
    tags:
    - who
    summary: "Update an existing entity"
    parameters:
    - $ref: "#/components/parameters/id"
    - $ref: "#/components/parameters/namespace"
    requestBody:
      description: "An entity where all fields are optional and modified is disallowed. Modifying sub-documents is possible via dot notation."
      content:
        $ref: "#/components/schemas/oneContent"
    responses:
      200:
        $ref: "#/components/schemas/200"

  patch:
    tags:
    - who
    summary: "Connect the entity identified by ?id to the supplied new entity"
    parameters:
    - $ref: "#/components/parameters/id"
    - $ref: "#/components/parameters/namespace"
    requestBody:
      description: "An entity where all fields are optional and modified is disallowed"
      content:
        $ref: "#/components/schemas/oneContent"
    responses:
      200:
        $ref: "#/components/schemas/200"

  delete:
    tags:
    - who
    summary: "Delete the specified entity, which is assumed to be a leaf, or only its connection if specified"
    parameters:
    - $ref: "#/components/parameters/id"
    - $ref: "#/components/parameters/namespace"
    - $ref: "#/components/parameters/connection"
    responses:
      200:
        $ref: "#/components/schemas/ok"

components:
  parameters:
    id:
      name: id
      in: query
      description: "An entity's unique name, case insensitive for reads"
      schema:
        type: string

    namespace:
      $ref: "./swagger.yaml#/components/parameters/namespace"

    connection:
      name: connection
      in: query
      description: "An entity's connection's name"
      schema:
        type: string

    light:
      name: light
      in: query
      description: "A lighter response body"
      schema:
        type: string

    md:
      name: md
      in: query
      description: "Include a html rendered markdown notes section as .md"
      schema:
        type: string

    order:
      name: order
      in: query
      description: "-1 for descending, the default, or 1 for ascending"
      schema:
        type: int

    sort:
      name: sort
      in: query
      description: "A field to sort entites by, defaults to `modified`"
      schema:
        type: string

    one:
      name: one
      in: body
      description: "An entire entity definition"
      schema:
        $ref: "#/components/schemas/one"

  schemas:
    oneContent:
      application/json:
        schema:
          $ref: "#/components/schemas/one"

    one:
      $ref: "./swagger.yaml#/components/schemas/one"

    200:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/one"

    ok:
      $ref: "./swagger.yaml#/components/schemas/ok"