paths:
  get:
    tags:
    - who
    summary: "Get an entity. If ?id not provided, see TRACE"
    parameters:
    - $ref: "#/components/parameters/id"
    - $ref: "#/components/parameters/namespace"
    - $ref: "#/components/parameters/light"
    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:
        application/json:
          schema:
            $ref: "#/components/schemas/one"
    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"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/one"
    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:
        application/json:
          schema:
            $ref: "#/components/schemas/one"
    responses:
      200:
        $ref: "#/components/schemas/200"

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

components:
  parameters:
    id:
      name: id
      in: query
      description: "An entity's unique name"
      schema:
        type: string

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

    light:
      name: light
      in: query
      description: "A lighter response body"
      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:
    one:
      title: "One entity"
      type: object
      properties:
        name:
          type: string
          example: "Jeff Snow"
        type:
          type: string
          example: "doggo"
        title:
          type: string
          example: "Meme Lord"
        text:
          type: string
          example: "Lorem ipsum"
        relationship:
          type: string
          example: "Good boi"
        modified:
          type: int
          example: 8675309
        attachments:
          type: object
          additionalProperties:
            type: string
        connections:
          type: object
          additionalProperties:
            type: object

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

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