swagger: '2.0'
info:
  title: Talk API
  description: A commenting platform from The Coral Project. https://coralproject.net
  version: "0.0.1"
host: talk-stg.coralproject.net
schemes:
  - https
basePath: /api/v1
consumes:
  - application/json
produces:
  - application/json

paths:
  /comments:
    get:
      tags:
        - Comments
      parameters:
        - name: action_type
          in: query
          description: Performs a search based on the actions that have been added to it.
          type: string
          enum:
            - rejected
            - accepted
            - new
      responses:
        200:
          description: Comments matching the query.
          schema:
            type: array
            items:
              $ref: '#/definitions/Comment'
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'
    post:
      tags:
        - Comments
      parameters:
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              body:
                type: string
                description: The text of the comment to create.
              asset_id:
                type: string
                description: The parent asset of this comment.
              parent_id:
                type: string
                description: The parent comment of this comment (null if the comment is not a reply.)
      responses:
        201:
          description: The comment that was created.
          schema:
            $ref: '#/definitions/Comment'
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'

  /comments/{comment_id}:
    get:
      tags:
        - Comments
      parameters:
        - name: comment_id
          in: path
          description: The id of the comment to retrieve.
          type: string
          required: true
      responses:
        200:
          description: The comment was found.
          schema:
            $ref: '#/definitions/Comment'
        404:
          description: The comment was not found.
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'
    delete:
      tags:
        - Comments
      parameters:
        - name: comment_id
          in: path
          description: The id of the comment to delete.
          type: string
          required: true
      responses:
        204:
          description: The comment was deleted.
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'

  /comments/{comment_id}/status:
    put:
      tags:
        - Comments
        - Moderation
      parameters:
        - name: comment_id
          in: path
          description: The id of the comment to retrieve.
          type: string
          format: uuid
          required: true
        - name: body
          in: body
          description: The status to update to.
          required: true
          schema:
            type: object
            properties:
              status:
                type: string
                description: The status to update to.
                enum:
                  - new
                  - flagged
                  - accepted
                  - rejected
      responses:
        204:
          description: The comment status was updated.
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'
  /comments/{item_id}/actions:
    post:
      tags:
        - Comments
        - Actions
      parameters:
        - name: item_id
          in: path
          description: The id of the item which is the target of the action.
          type: string
          required: true
        - name: body
          in: body
          description: The action to add.
          required: true
          schema:
            type: object
            properties:
              action_type:
                type: string
                description: The type of action to add
                enum:
                  - like
                  - flag
              metadata:
                type: object
                description: An arbitrary object describing the action, should be consistent per action type.
      responses:
        201:
          description: The action created.
          schema:
            $ref: '#/definitions/Action'
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'
  /actions/{action_id}:
    delete:
      tags:
        - Actions
      parameters:
        - name: action_id
          in: path
          description: The id of the action to delete.
          type: string
          required: true
      responses:
        204:
          description: The action was deleted.
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'
  /auth:
    get:
      tags:
        - Auth
      description: Retrieves the current authentication credentials.
      responses:
        200:
          description: The current user.
          schema:
            $ref: '#/definitions/User'
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'
    delete:
      tags:
        - Auth
      description: Logs out the current authenticated user.
      responses:
        204:
          description: The current user has been logged out.
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'
  /auth/local:
    post:
      tags:
        - Auth
      parameters:
        - name: body
          in: body
          required: true
          description: The login credentials.
          schema:
            type: object
            properties:
              email:
                type: string
                description: The email address of the current user.
              password:
                type: string
                description: The password of the current user.
      responses:
        200:
          description: The user has authenticated sucesfully.
          schema:
            $ref: '#/definitions/User'
        401:
          description: The authentication error.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'
  /auth/facebook:
    get:
      tags:
        - Auth
      responses:
        302:
          description: Redirects the user to perform external facebook authentication.
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'
  /auth/facebook/callback:
    get:
      tags:
        - Auth
      responses:
        200:
          description: Logs in the user after FB Auth.
          schema:
            $ref: '#/definitions/User'
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'
  /queue/comments/pending:
    get:
      tags:
        - Comments
        - Moderation
      responses:
        200:
          description: The comments that are not moderated.
          schema:
            type: object
            properties:
              comments:
                type: array
                description: The comments that have yet to be moderated.
                items:
                  $ref: '#/definitions/Comment'
              users:
                type: array
                description: The users authoring these comments.
                items:
                  $ref: '#/definitions/User'
              actions:
                type: array
                description: The actions which have taken place on these comments.
                items:
                  $ref: '#/definitions/Actions'
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'
  /assets:
    get:
      parameters:
        - name: limit
          in: query
          type: number
          format: int32
          description: Limit the listing results
        - name: skip
          in: query
          type: number
          format: int32
          description: Skip the listing results
        - name: sort
          in: query
          enum:
            - asc
            - desc
          type: string
          description: Sorting method
        - name: field
          in: query
          type: string
          description: Field to sort by.
        - name: filter
          in: query
          type: string
          enum:
            - open
            - closed
          description: Comment status to filter by.
        - name: search
          in: query
          type: string
          description: String to search by.
      responses:
        200:
          description: Assets listed.
          schema:
            type: object
            properties:
              count:
                type: number
                description: Total number of assets found.
              result:
                type: array
                items:
                  $ref: '#/definitions/Asset'

  /assets/{asset_id}:
    get:
      parameters:
        - name: asset_id
          in: path
          required: true
          type: string
          format: uuid
      responses:
        200:
          description: The requested asset.
          schema:
            $ref: '#/definitions/Asset'
        404:
          description: The asset was not found.
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'


  /assets/{asset_id}/scrape:
    post:
      parameters:
        - name: asset_id
          in: path
          required: true
          type: string
          format: uuid
      responses:
        201:
          description: The job that was created.
          schema:
            $ref: '#/definitions/Job'
        404:
          description: The asset was not found.
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'

  /assets/{asset_id}/settings:
    put:
      parameters:
        - name: asset_id
          in: path
          required: true
          type: string
          format: uuid
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/Settings'
      responses:
        204:
          description: The asset settings were updated.
        404:
          description: The asset was not found.
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'

  /assets/{asset_id}/status:
    put:
      parameters:
        - name: asset_id
          required: true
          in: path
          type: string
          format: uuid
          description: The id of the asset to be updated
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              closedAt:
                type: number
                description: The Unix timestamp when the stream will be or was previously closed.
              closedMessage:
                type: string
                description: The message to display to users when the stream is closed.
      responses:
        204:
          description: Status update successful.
        500:
          description: An error has occurred.
          schema:
            $ref: '#/definitions/Error'
  /stream:
    get:
      tags:
        - Actions
        - Assets
        - Comments
        - Users
      parameters:
        - name: asset_url
          in: query
          description: The url of the asset for which to get the comment stream.
          type: string
          format: url
      responses:
        200:
          description: The comment stream.
          schema:
            type: object
            properties:
              asset:
                $ref: '#/definitions/Asset'
              comments:
                type: array
                description: All comments for this asset.
                items:
                  $ref: '#/definitions/Comment'
              users:
                type: array
                description: All authors of comments on this asset.
                items:
                  $ref: '#/definitions/User'
              actions:
                type: array
                description: All actions on comments on this asset and their authors.
                items:
                  $ref: '#/definitions/Actions'
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'
  /settings:
    get:
      responses:
        200:
          description: All global settings.
          schema:
            $ref: '#/definitions/Settings'
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'
    put:
      parameters:
        - name: body
          in: body
          required: true
          description: Settings to be updated.
          schema:
            type: object
            description: Any allowed setting and value.
      responses:
        204:
          description: The settings were updated.
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'
  /users:
    get:
      parameters:
       - name: value
         in: query
         type: string
         description: A term to search users' usernames and email addresses.
       - name: sort
         in: query
         type: string
         enum:
          - asc
          - desc
         description: Determines whether users sorted in are ascending or descending order.
       - name: field
         in: query
         type: string
         description: The field used to sort.
       - name: page
         in: query
         type: number
         description: The page of search results to return.
       - name: limit
         in: query
         type: number
         description: The number of search restults per page.
      responses:
        200:
          description: A paginated array of users matching search terms.
          schema:
            type: object
            properties:
              result:
                type: array
                description: Users matching search criteria.
                items:
                  $ref: '#/definitions/User'
              limit:
                type: number
                description: Results per page.
              count:
                type: number
                description: Total number of results.
              page:
                type: number
                description: The current page.
              totalPages:
                type: number
                description: The total number of pages.
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'
    post:
      parameters:
        - name: body
          in: body
          required: true
          description: User to be created.
          schema:
            type: object
            properties:
              email:
                type: string
                format: email
              password:
                type: string
              username:
                type: string
      responses:
        201:
          description: The user that has been created.
          schema:
            $ref: '#/definitions/User'
  /account/password/reset:
    post:
      parameters:
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              token:
                type: string
                description: The token that was in the url of the email link.
              password:
               type: string
               description: The new password.
      responses:
        204:
          description: Password update successful.
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'
  /request-password-reset:
    post:
      parameters:
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              email:
                type: string
                description: The email address of the user whos password is being reset.
      responses:
        204:
          description: Returned regardless of whether the user was found in the DB.
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'
  /users/{user_id}/role:
    post:
      parameters:
        - name: user_id
          in: path
          required: true
          type: string
          format: uuid
          description: ID of the user to be updated.
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              role:
                type: string
                description: Role to be added to the user.
                enum:
                  - admin
                  - moderator
      responses:
        204:
          description: Role update successful.
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'
  /users/{user_id}/status:
    post:
      parameters:
        - name: user_id
          in: path
          type: string
          format: uuid
          required: true
          description: ID of the user to be updated.
        - name: body
          in: body
          required: true
          schema:
           type: object
           properties:
            status:
              type: string
              description: Status for the user to be set to.
              enum:
                - active
                - banned
            comment_id:
              type: string
              format: uuid
              description: The id of the comment which triggered this status change.
      responses:
        200:
          description: Status update successful.
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'
  /users/{user_id}/bio:
    put:
      parameters:
        - name: user_id
          in: path
          required: true
          type: string
          format: uuid
          description: The id of the user being updated.
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              bio:
                type: string
                description: The bio that should be set for this user.
      responses:
        200:
          description: Status update successful.
          schema:
            $ref: '#/definitions/User'
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'
  /{user_id}/actions:
    post:
      parameters:
        - name: user_id
          in: path
          required: true
          type: string
          format: uuid
          description: The user on which this action is being taken.
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              action_type:
                description: The type of action being taken on this user.
                type: string
                enum:
                  - flag
              metadata:
                type: object
                description: Arbitrary data to be included with the action.
      responses:
        200:
          description: The newly created action.
          schema:
            $ref: '#/definitions/Action'
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'

definitions:
  Error:
    type: object
    properties:
      message:
        type: string
        description: The error that occured.
  Comment:
    type: object
    properties:
      id:
        type: string
        description: Unique identifier
      body:
        type: string
        description: Description of comment
      created_at:
        type: string
        format: date-time
        description: Display name of comment
      updated_at:
        type: string
        format: date-time
        description: Display name of comment
      author_id:
        type: string
        description: User who posted the comment
      parent_id:
        type: string
        description: Display name of comment
      asset_id:
        type: string
        description: Display name of comment
      status_history:
        type: array
        description: A history of status changes for this comment.
        items:
          type: object
          properties:
            type:
              type: string
              enum:
                - accepted
                - rejected
                - premod
            assigned_by:
              type: string
              description: ID of the user who assigned this status.
            created_at:
              type: string
              format: date-time
              description: Date when status was assigned.

  Actions:
    type: object
    description: A summary of actions taken on a particular item which is with the comment stream.
    properties:
      item_id:
        type: string
        description: The ID of the item which these actions target
      item_type:
        type: string
        description: The type of item which these actions target (comment, user, etc.)
      type:
        type: string
        description: The type of action (like, flag, etc.)
      count:
        type: integer
        description: The number of this type of actions performed on this item.
      metadata:
        type: array
        items:
          type: object
          description: Metadata from the actions performed on this item. This metadata can be defined differently for each action type.
      current_user:
        type: object
        description: Will include the action performed by the currently logged in user if that user has taken an action on this item. Otherwise will return null.
      created_at:
        type: string
        format: date-time
        description: Oldest created_at of actions in this set.
      updated_at:
        type: string
        format: date-time
        description: Newest updated_at of actions in this set.
  Action:
    type: object
    description: A single action taken by a user.
    properties:
      id:
        type: string
        description: The uuid.v4 id of the action.
      type:
        type: string
        description: The type of action being taken (like, flag, etc.)
      user_id:
        type: string
        description: The ID of the user taking this action.
      metadata:
        type: object
        description: An object which contains arbitrary metadata about the action. Should be consistent for each action_type.
      created_at:
        type: string
        format: date-time
        description: Creation Date-Time
      updated_at:
        type: string
        format: date-time
        description: Updated Date-Time
  Asset:
    type: object
    properties:
      id:
        type: string
        description: The uuid.v4 id of the asset.
      url:
        type: string
        description: The url where the asset is found.
      type:
        type: string
        description: What kind of asset it is.
        default: article
      headline:
        type: string
        description: The headline of the asset, inferred on initial load.
      summary:
        type: string
        description: A summary of the asset, inferred on initial load.
      section:
        type: string
        description: The section the asset is in.
      subsection:
        type: string
        description: The subsection that the asset is in.
      authors:
        type: string
        description: An array of the authors for this asset.
      publication_date:
        type: string
        format: datetime
        description: When this asset was published.
      created_at:
        type: string
        format: date-time
        description: Creation Date-Time
      updated_at:
        type: string
        format: date-time
        description: Updated Date-Time
  User:
    type: object
    properties:
      id:
        type: string
        description: The uuid.v4 id of the user.
      username:
        type: string
        description: The name appearing next to the user's comments.
      disabled:
        type: boolean
        description: Indicates whether the user's account has been disabled (ie if the user is banned).
      password:
        type: string
        description: This provides a source of identity proof for users who login using the local provider. A local provider will be assumed for users who do not have any social profiles.
      profiles:
        type: array
        description: The array of identities for a given user. Any one user can have multiple profiles associated with them (eg facebook, google, etc.)
        items:
          type: object
          properties:
              id:
                type: string
                description: A unique identifier for the profile.
              provider:
                type: string
                description: The ame of the identity provider being used (e.g. 'facebook', 'twitter', etc.)
      roles:
        type: array
        items:
          type: string
        description: Roles occupied by the user (e.g. 'ADMIN', 'MODERATOR', etc.)
      status:
        type: string
        description: The current status of the user in the system.
        enum:
          - active
          - banned
      settings:
        type: object
        description: User-specific settings
        properties:
          bio:
            type: string
            description: A bio visible to other users.
      created_at:
        type: string
        format: date-time
        description: Creation Date-Time
      updated_at:
        type: string
        format: date-time
        description: Updated Date-Time
  Settings:
    type: object
    properties:
        id:
          type: string
          description: The id of the settings object. Defaults to 1 for global settings.
        moderation:
          type: string
          enum:
            - pre
            - post
          description: Indicates whether moderation occurs before or after a comment is made publicly visible.
        infoBoxEnable:
          type: boolean
          description: Indicates whether an informational box will be shown above the comment input box.
        infoBoxContent:
          type: string
          description: The text to appear in the informational box.
        closedTimeout:
          type: number
          format: int32
          description: The time after which streams will be automatically closed in seconds. Null will keep streams open forever.
        closedMessage:
          type: string
          description: The message displayed when a stream is closed.
        wordlist:
          type: array
          description: A list of banned word which will cause a comment to be automatically rejected.
          items:
            type: string
        charCount:
          type: number
          format: int32
          description: The maximum number of characters allowed in a comment.
        charCountEnable:
          type: boolean
          description: Indicates whether a maximum character count should be enabled for comments.
        created_at:
          type: string
          format: date-time
          description: Creation Date-Time
        updated_at:
          type: string
          format: date-time
          description: Updated Date-Time
  Job:
    type: object
    properties:
      id:
        format: number
      state:
        format: string