swagger: '2.0'

info:
  version: "1.0.0-SNAPSHOT"
  title: interaction-service

host: haleconnect.com
schemes:
  - https
basePath: /interactions

paths:

  /resources/{ownerType}/{ownerId}:
    parameters:
      - $ref: "#/parameters/ownerTypeParam"
      - $ref: "#/parameters/ownerIdParam"
      - $ref: "#/parameters/ownerIdHeader"

    delete:
      tags:
        - Purge

      summary: Deletes all resources associated to an owner
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/IdentifierArray'
        default:
          $ref: '#/responses/Error'

  /comments/{resourceType}/{resourceId}:
    parameters:
      - $ref: "#/parameters/resourceTypeParam"
      - $ref: "#/parameters/resourceIdParam"

    get:
      tags:
        - Comments
      summary: List of comments for a resource
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/CommentList'
        default:
          $ref: '#/responses/Error'

    post:
      tags:
        - Comments
      summary: Create a new comment
      consumes:
        - text/plain
        - application/json
      parameters:
        - $ref: "#/parameters/bodyParam"
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'


  /comments/{resourceType}/{resourceId}/{slug}:
    parameters:
      - $ref: "#/parameters/resourceTypeParam"
      - $ref: "#/parameters/resourceIdParam"
      - $ref: "#/parameters/slugParam"

    delete:
      tags:
        - Comments
      summary: Deletes a comment
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

    put:
      tags:
        - Comments
      summary: Edits a comment
      consumes:
        - text/plain
        - application/json
      parameters:
        - $ref: "#/parameters/bodyParam"
      responses:
        200:
          description: Successful response
          schema:
           $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

    get:
      tags:
        - Comments
      summary: Get a specific comment
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Comment'
        default:
          $ref: '#/responses/Error'

  /comments/{resourceType}/{resourceId}/sub/{subresourceId}:
    parameters:
      - $ref: "#/parameters/resourceTypeParam"
      - $ref: "#/parameters/resourceIdParam"
      - $ref: "#/parameters/subresourceIdParam"

    get:
      tags:
        - Comments
      summary: List of comments for a resource
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/CommentList'
        default:
          $ref: '#/responses/Error'

    post:
      tags:
        - Comments
      summary: Add a new comment
      consumes:
        - text/plain
        - application/json
      parameters:
        - $ref: "#/parameters/bodyParam"
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'


  /comments/{resourceType}/{resourceId}/sub/{subresourceId}/{slug}:
    parameters:
      - $ref: "#/parameters/resourceTypeParam"
      - $ref: "#/parameters/resourceIdParam"
      - $ref: "#/parameters/subresourceIdParam"
      - $ref: "#/parameters/slugParam"

    delete:
      tags:
        - Comments
      summary: Delete a comment
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

    put:
      tags:
        - Comments
      summary: Edits a comment
      consumes:
        - text/plain
        - application/json
      parameters:
        - $ref: "#/parameters/bodyParam"
      responses:
        200:
          description: Successful response
          schema:
           $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

    get:
      tags:
        - Comments
      summary: Get a specific comment
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Comment'
        default:
          $ref: '#/responses/Error'


  /comments/replies/{resourceType}/{resourceId}/{parentSlug}:
    parameters:
      - $ref: "#/parameters/resourceTypeParam"
      - $ref: "#/parameters/resourceIdParam"
      - $ref: "#/parameters/parentSlugParam"

    post:
      tags:
        - Comments
      summary: Add a reply to a comment
      consumes:
        - text/plain
        - application/json
      parameters:
        - $ref: "#/parameters/bodyParam"
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

  /comments/{resourceType}/{resourceId}/{parentSlug}/replies/{slug}:
    parameters:
      - $ref: "#/parameters/resourceTypeParam"
      - $ref: "#/parameters/resourceIdParam"
      - $ref: "#/parameters/parentSlugParam"
      - $ref: "#/parameters/slugParam"

    delete:
      tags:
        - Comments
      summary: Delete a reply to a comment
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

    put:
      tags:
        - Comments
      summary: Edits a reply to a comment
      consumes:
        - text/plain
        - application/json
      parameters:
        - $ref: "#/parameters/bodyParam"
      responses:
        200:
          description: Successful response
          schema:
           $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

    get:
      tags:
        - Comments
      summary: Get a specific reply to a comment
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Comment'
        default:
          $ref: '#/responses/Error'


  /comments/replies/{resourceType}/{resourceId}/sub/{subresourceId}/{parentSlug}:
    parameters:
      - $ref: "#/parameters/resourceTypeParam"
      - $ref: "#/parameters/resourceIdParam"
      - $ref: "#/parameters/subresourceIdParam"
      - $ref: "#/parameters/parentSlugParam"

    post:
      tags:
        - Comments
      summary: Add a reply to a comment
      consumes:
        - text/plain
        - application/json
      parameters:
        - $ref: "#/parameters/bodyParam"
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

  /count/comments/{resourceType}/{resourceId}:
    parameters:
      - $ref: "#/parameters/resourceTypeParam"
      - $ref: "#/parameters/resourceIdParam"

    get:
      tags:
        - Comments
      summary: Get the number of unread comments for a user and resource.
      responses:
        200:
          description: Successful response
          schema:
            type: integer
            format: int32
        default:
          $ref: '#/responses/Error'

  /count/comments/{resourceType}/{resourceId}/sub/{subresourceId}:
    parameters:
      - $ref: "#/parameters/resourceTypeParam"
      - $ref: "#/parameters/resourceIdParam"
      - $ref: "#/parameters/subresourceIdParam"
    get:
      tags:
        - Comments
      summary: Get the number of unread comments for a user and subresource
      responses:
        200:
          description: Successful response
          schema:
            type: integer
            format: int32
        default:
          $ref: '#/responses/Error'

  /notes/{resourceType}/{resourceId}:
    parameters:
      - $ref: "#/parameters/resourceTypeParam"
      - $ref: "#/parameters/resourceIdParam"

    get:
      tags:
        - Notes
      summary: List notes for a resource and user
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/NoteList'
        default:
          $ref: '#/responses/Error'

    post:
      tags:
        - Notes
      summary: Add a new note
      consumes:
        - text/plain
      parameters:
        - $ref: "#/parameters/bodyParam"
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

  /notes/{resourceType}/{resourceId}/sub/{subresourceId}:
    parameters:
      - $ref: "#/parameters/resourceTypeParam"
      - $ref: "#/parameters/resourceIdParam"
      - $ref: "#/parameters/subresourceIdParam"

    get:
      tags:
        - Notes
      summary: List notes for a subresource and user
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/NoteList'
        default:
          $ref: '#/responses/Error'

    post:
      tags:
        - Notes
      summary: Add a new note for a subresource
      consumes:
        - text/plain
      parameters:
        - $ref: "#/parameters/bodyParam"
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

  /notes/{resourceType}/{resourceId}/{slug}:
    parameters:
      - $ref: "#/parameters/resourceTypeParam"
      - $ref: "#/parameters/resourceIdParam"
      - $ref: "#/parameters/slugParam"

    put:
      tags:
        - Notes
      summary: Edit a note
      consumes:
        - text/plain
      parameters:
        - $ref: "#/parameters/bodyParam"
      responses:
        200:
          description: Successful response
          schema:
           $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

    delete:
      tags:
        - Notes
      summary: Delete a note
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

  /notes/{resourceType}/{resourceId}/sub/{subresourceId}/{slug}:
    parameters:
      - $ref: "#/parameters/resourceTypeParam"
      - $ref: "#/parameters/resourceIdParam"
      - $ref: "#/parameters/subresourceIdParam"
      - $ref: "#/parameters/slugParam"
    put:
      tags:
        - Notes
      summary: Edit a note
      consumes:
        - text/plain
      parameters:
        - $ref: "#/parameters/bodyParam"
      responses:
        200:
          description: Successful response
          schema:
           $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

    delete:
      tags:
        - Notes
      summary: Delete a note
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

  /count/notes/{resourceType}/{resourceId}:
    parameters:
      - $ref: "#/parameters/resourceTypeParam"
      - $ref: "#/parameters/resourceIdParam"

    get:
      tags:
        - Notes
      summary: Count the notes for a resource and user
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/NoteList'
        default:
          $ref: '#/responses/Error'

  /count/notes/{resourceType}/{resourceId}/sub/{subresourceId}:
    parameters:
      - $ref: "#/parameters/resourceTypeParam"
      - $ref: "#/parameters/resourceIdParam"
      - $ref: "#/parameters/subresourceIdParam"

    get:
      tags:
        - Notes
      summary: Count the notes for a subresource and user
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/NoteList'
        default:
          $ref: '#/responses/Error'

  /tasks/{resourceType}/{resourceId}:
    parameters:
      - $ref: "#/parameters/resourceTypeParam"
      - $ref: "#/parameters/resourceIdParam"

    get:
      tags:
        - Tasks
      summary: List of tasks for a resource
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/TaskList'
        default:
          $ref: '#/responses/Error'

    post:
      tags:
        - Tasks
      summary: Add a new task for a resource
      consumes:
        - application/json
      parameters:
        - $ref: "#/parameters/taskInfoParam"
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

  /tasks/{resourceType}/{resourceId}/sub/{subresourceId}:
    parameters:
      - $ref: "#/parameters/resourceTypeParam"
      - $ref: "#/parameters/resourceIdParam"
      - $ref: "#/parameters/subresourceIdParam"
    get:
      tags:
        - Tasks
      summary: List of tasks for a subresource
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/TaskList'
        default:
          $ref: '#/responses/Error'

    post:
      tags:
        - Tasks
      summary: Add a new task for a subresource
      consumes:
        - application/json
      parameters:
        - $ref: "#/parameters/taskInfoParam"
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

  /tasks/{resourceType}/{resourceId}/{slug}:
    parameters:
      - $ref: "#/parameters/resourceTypeParam"
      - $ref: "#/parameters/resourceIdParam"
      - $ref: "#/parameters/slugParam"

    get:
      tags:
        - Tasks
      summary: Get information on a task
      consumes:
        - application/json
      responses:
        200:
          description: Successful response
          schema:
           $ref: '#/definitions/Task'
        default:
          $ref: '#/responses/Error'

    put:
      tags:
        - Tasks
      summary: Edit a task for a resource
      consumes:
        - application/json
      parameters:
        - $ref: "#/parameters/taskUpdateParam"
      responses:
        200:
          description: Successful response
          schema:
           $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

    delete:
      tags:
        - Tasks
      summary: Delete a task for a resource
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

  /tasks/{resourceType}/{resourceId}/sub/{subresourceId}/{slug}:
    parameters:
      - $ref: "#/parameters/resourceTypeParam"
      - $ref: "#/parameters/resourceIdParam"
      - $ref: "#/parameters/subresourceIdParam"
      - $ref: "#/parameters/slugParam"

    get:
      tags:
        - Tasks
      summary: Get information on a task
      consumes:
        - application/json
      responses:
        200:
          description: Successful response
          schema:
           $ref: '#/definitions/Task'
        default:
          $ref: '#/responses/Error'

    put:
      tags:
        - Tasks
      summary: Update a task for a subresource
      consumes:
        - application/json
      parameters:
        - $ref: "#/parameters/taskUpdateParam"
      responses:
        200:
          description: Successful response
          schema:
           $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

    delete:
      tags:
        - Tasks
      summary: Delete a task for a subresource
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

  /count/tasks/{resourceType}/{resourceId}:
    parameters:
      - $ref: "#/parameters/resourceTypeParam"
      - $ref: "#/parameters/resourceIdParam"

    get:
      tags:
        - Tasks
      summary: Get the number of tasks for a resource
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/TaskCount'
        default:
          $ref: '#/responses/Error'

  /count/tasks/{resourceType}/{resourceId}/sub/{subresourceId}:
    parameters:
      - $ref: "#/parameters/resourceTypeParam"
      - $ref: "#/parameters/resourceIdParam"
      - $ref: "#/parameters/subresourceIdParam"
    get:
      tags:
        - Tasks
      summary: Get the number of tasks for a subresource
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/TaskCount'
        default:
          $ref: '#/responses/Error'


  /forum/threads:
    get:
      tags:
        - Forum
      summary: Get the existing threads in the forum
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/TaskList'
        default:
          $ref: '#/responses/Error'

    post:
      tags:
        - Forum
      summary: Add a new thread to the forum
      consumes:
        - application/json
      parameters:
        - $ref: "#/parameters/taskInfoParam"
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

  /forum/threads/{threadId}:
    parameters:
      - $ref: "#/parameters/threadIdParam"

    get:
      tags:
        - Forum
      summary: Get information on a thread
      consumes:
        - application/json
      responses:
        200:
          description: Successful response
          schema:
           $ref: '#/definitions/Task'
        default:
          $ref: '#/responses/Error'


    put:
      tags:
        - Forum
      summary: Update the content of a forum
      consumes:
        - application/json
      parameters:
        - $ref: "#/parameters/threadInfoParam"
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'


    delete:
      tags:
        - Forum
      summary: Delete a thread in the forum
      responses:
        200:
          description: Successful response
          schema:
           $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

  /forum/threads/{threadId}/comments:
    parameters:
      - $ref: "#/parameters/threadIdParam"

    get:
      tags:
        - Forum
      summary: List of comments for a thread
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/CommentList'
        default:
          $ref: '#/responses/Error'

    post:
      tags:
        - Forum
      summary: Create a new comment in a thread
      consumes:
        - text/plain
      parameters:
        - $ref: "#/parameters/bodyParam"
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

  /forum/threads/{threadId}/comments/{commentId}/replies:
    parameters:
      - $ref: "#/parameters/threadIdParam"
      - $ref: "#/parameters/commentIdParam"

    post:
      tags:
        - Forum
      summary: Add a reply to a comment within a forum thread
      consumes:
        - text/plain
      parameters:
        - $ref: "#/parameters/bodyParam"
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

  /forum/threads/{threadId}/comments/count:
    parameters:
      - $ref: "#/parameters/threadIdParam"

    get:
      tags:
        - Forum
      summary: Get the number of comments for a forum thread.
      responses:
        200:
          description: Successful response
          schema:
            type: integer
            format: int32
        default:
          $ref: '#/responses/Error'


  /forum/threads/{threadId}/comments/{commentId}:
    parameters:
      - $ref: "#/parameters/threadIdParam"
      - $ref: "#/parameters/commentIdParam"

    put:
      tags:
        - Forum
      summary: Updates a comment within a forum thread
      consumes:
        - text/plain
      parameters:
        - $ref: "#/parameters/bodyParam"
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

    delete:
      tags:
        - Forum
      summary: Deletes a comment within a forum thread
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Feedback'
        default:
          $ref: '#/responses/Error'

parameters:

  ownerTypeParam:
      name: ownerType
      in: path
      description: The type of owner the resource belongs to
      required: true
      type: string
      enum:
        - user
        - org

  ownerIdParam:
      name: ownerId
      in: path
      description: The ID of the resource's owner
      required: true
      type: string

  ownerIdHeader:
      name: WETF-Context-Organisation
      in: header
      description: The current organisation context
      required: true
      type: string

  resourceTypeParam:
      name: resourceType
      in: path
      description: The type of the resource
      required: true
      type: string

  resourceIdParam:
      name: resourceId
      in: path
      description: The composed id of the resource
      required: true
      type: string

  subresourceIdParam:
      name: subresourceId
      in: path
      description: The composed id of the subresource
      required: true
      type: string

  slugParam:
      name: slug
      in: path
      description: The slug of the post
      required: true
      type: string

  parentSlugParam:
      name: parentSlug
      in: path
      description: The slug of the comment to reply to
      required: true
      type: string

  bodyParam:
      name: body
      in: body
      description: The note content
      schema:
        type: string

  taskInfoParam:
      name: taskInfo
      in: body
      description: Additional task information
      schema:
        $ref: '#/definitions/TaskInformation'

  taskUpdateParam:
      name: taskUpdate
      in: body
      description: Task update information
      schema:
        $ref: '#/definitions/TaskUpdate'


  threadInfoParam:
      name: threadInfo
      in: body
      description: Additional Forum thread information
      schema:
        $ref: '#/definitions/ThreadInformation'

  threadIdParam:
      name: threadId
      in: path
      description: The id of the thread
      required: true
      type: string

  commentIdParam:
      name: commentId
      in: path
      description: The id of the comment
      required: true
      type: string

definitions:

  Feedback:
    type: object
    required:
      - code
      - message
      - error
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      error:
        type: boolean

  Comment:
    type: object
    properties:
      author:
        description: The comment author
        type: string
      posted:
        description: The time the comment was posted
        type: string
        format: date-time
      body:
        description: The comment text
        type: string
      slug:
        description: The slug identifier of the comment
        type: string
      lastReply:
        description: The last reply
        type: string
        format: date-time
      replies:
        $ref: "#/definitions/CommentList"
    required:
      - author
      - posted
      - body
      - slug
      - lastReply
      - replies

  CommentList:
    description: Array of comments
    type: array
    items:
      $ref: '#/definitions/Comment'

  IdentifierArray:
    description: Array with the identifier associated with the deleted resources
    type: array
    items:
      type: string
      description: ID associated to the resource deleted


  Note:
    type: object
    properties:
      author:
        description: The note author
        type: string
      posted:
        description: The time the note was posted
        type: string
        format: date-time
      body:
        description: The note text
        type: string
      slug:
        description: The slug identifier of the note
        type: string
    required:
      - author
      - posted
      - body
      - slug

  NoteList:
    description: Array of notes
    type: array
    items:
      $ref: '#/definitions/Note'

  Assignee:
    type: object
    properties:
      type:
        description: The assignee type
        type: string
        enum:
          - user
          - org
      id:
        description: The assignee id
        type: string

  Task:
    type: object
    properties:
      author:
        description: The task author
        type: string
      posted:
        description: The time the task was posted
        type: string
        format: date-time
      title:
        description: The title of the task
        type: string
      body:
        description: The task description
        type: string
      assignees:
        description: Array of assignees
        type: array
        items:
          $ref: '#/definitions/Assignee'
      status:
        description: The task status
        type: string
        enum:
          - open
          - done
      slug:
        description: The slug identifier of the task
        type: string
    required:
      - author
      - posted
      - body
      - slug

  TaskList:
    description: Array of tasks
    type: array
    items:
      $ref: '#/definitions/Task'

  TaskInformation:
    type: object
    description: An object containing all mandatory task information
    properties:
      title:
        description: The title of the task
        type: string
      description:
        description: The task description
        type: string
      assignees:
        description: Array of assignees
        type: array
        items:
          $ref: '#/definitions/Assignee'
    required:
      - title
      - description

  ThreadInformation:
    type: object
    description: An object containing all mandatory forum thread information
    properties:
      title:
        description: The title of the thread
        type: string
      description:
        description: The thread description
        type: string
    required:
      - title
      - description


  TaskUpdate:
    type: object
    description: An object indicating which task fields to be update
    properties:
      title:
        description: The title of the task
        type: string
      description:
        description: The task description
        type: string
      assignees:
        description: Array of assignees
        type: array
        items:
          $ref: '#/definitions/Assignee'

  TaskCount:
    type: object
    description: An object containing task count information
    properties:
      total:
        description: The total number of tasks
        type: integer
      open:
        description: The number of open tasks
        type: integer
      done:
        description: The number of done tasks
        type: integer
    required:
      - total
      - open
      - done


responses:

  Error:
    description: Internal error processing request
    schema:
      $ref: '#/definitions/Feedback'
