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: status
          in: query
          description: Performs a search based on the comment's status.
          type: string
          enum:
            - flag
        - 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
          description: The comment to create.
          schema:
            $ref: '#/definitions/Comment'
      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
          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.
      responses:
        204:
          description: The comment status was updated.
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'
  /comments/{comment_id}/actions:
    post:
      tags:
        - Comments
        - Actions
      parameters:
        - name: comment_id
          in: path
          description: The id of the comment to retrieve.
          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 action to add
      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'
  /queue/comments/pending:
    get:
      tags:
        - Comments
        - Moderation
      responses:
        200:
          description: The comments that are not moderated.
          schema:
            type: array
            items:
              - $ref: '#/definitions/Comment'
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'
  /asset:
    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.
      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'

  /asset/{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'


  /asset/{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'

  /asset/{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'

  /stream:
    get:
      tags:
        - Actions
        - Assets
        - Comments
        - Users
      parameters:
        - name: asset_url
          in: query
          description: The asset url to get the comment stream from.
          type: string
          format: url
      responses:
        200:
          description: The comment stream.
          schema:
            type: object
            properties:
              assets:
                type: array
                items:
                  - $ref: '#/definitions/Asset'
              comments:
                type: array
                items:
                  - $ref: '#/definitions/Comment'
              users:
                type: array
                items:
                  - $ref: '#/definitions/User'
              actions:
                type: array
                items:
                  - $ref: '#/definitions/Actions'
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'
  /settings:
    get:
      responses:
        200:
          description: The settings.
          schema:
            $ref: '#/definitions/Settings'
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'
    put:
      responses:
        204:
          description: The settings were updated.
        500:
          description: An error occured.
          schema:
            $ref: '#/definitions/Error'
definitions:
  Error:
    type: object
    properties:
      message:
        type: string
        description: The error that occured.
  Item:
    type: object
  ModerationAction:
    type: string
  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
  Actions:
    type: object
    properties:
      item_id:
        type: string
      item_type:
        type: string # comment, user...
      type:
        type: string # flagged, likes, upvotes...
      count:
        type: integer
      current_user:
        type: boolean
  Action:
    type: object
    properties:
      type:
        type: string
      user_id:
        type: string
      moderation:
        type: string
        enum:
            - pre
            - post
      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.
  User:
    type: object
  Settings:
    type: object
  Job:
    type: object
    properties:
      id:
        format: number
      state:
        format: string