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:
  /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