talk/swagger.yaml

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
produces:
  - application/json
paths:
  /comments:
    # get:
    #   tags:
    #     - Comments
    #   produces:
    #   - application/json
    #   summary: Comment Types
    #   description: |
    #     This endpoint retrieves comments
    #   parameters:
    #     - name: id
    #       in: query
    #       description: Comment by id
    #       required: false
    #       type: string
    #   responses:
    #     200:
    #       description: An array of comments
    #       schema:
    #         type: array
    #         items:
    #           $ref: '#/definitions/Comment'
    post:
      description: Add a new comment
      parameters:
        - name: body
          in: body
          description: Body
          required: true
          schema:
            $ref: '#/definitions/Comment'
      responses:
        201:
          description: "OK: Comment Added"
          schema:
              $ref: '#/definitions/Comment'
        500:
          description: "Error"
  /comments/{comment_id}/actions:
    post:
      tags:
        - Comments
      description: Add a action
      parameters:
        - name: comment_id
          in: path
          description: Comment ID
          required: true
          type: string
        - name: body
          in: body
          description: comment
          required: true
          schema:
            $ref: '#/definitions/Action'
      responses:
        201:
          description: Action Added
          schema:
            type: array
            items:
              $ref: '#/definitions/Comment'
  /comments/{comment_id}/status:
    post:
      tags:
        - Comments
      description: Add a new status
      parameters:
        - name: comment_id
          in: path
          description: Comment ID
          required: true
          type: string
        - name: body
          in: body
          description: comment
          required: true
          schema:
            $ref: '#/definitions/ModerationAction'
      responses:
        204:
          description: ModerationAction Added
  /queue:
    get:
      tags:
        - Queue
      description: Queue
      parameters:
        - name: type
          in: query
          description:
            "pending: no status | flagged: flagged action + no status | rejected: rejected status"
          required: true
          type: string
          enum:
            - pending
            - flagged
            - rejected
        - name: limit
          in: query
          description: Queue limit
          required: false
          type: integer
        - name: skip
          in: query
          description: Skip
          required: false
          type: integer
      responses:
        200:
          description: ModerationAction Added
          schema:
            type: array
            items:
              $ref: '#/definitions/ModerationAction'
  /stream:
    get:
      tags:
        - Stream
      description: Stream
      parameters:
        - name: asset_id
          in: query
          description: Description
          required: true
          type: string
      responses:
        200:
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/Item'
  /settings:
    get:
      tags:
        - Settings
      description: Settings
      responses:
        200:
          description: Get Setting
          schema:
            type: array
            items:
              $ref: '#/definitions/Setting'
    put:
      tags:
        - Settings
      description: Settings
      responses:
        204:
          description: OK
  /asset:
    get:
      tags:
        - Asset
      description: Get an asset by id.
      responses:
        200:
          description: OK
    put:
      tags:
        - Asset
      description: Upsert an asset.
      responses:
        204:
          description: OK
  /asset?url={url}:
    get:
      tags:
        - Asset
      parameters:
        - name: url
          in: query
          description: The url of the asset.
          required: true
      description: Get an asset by its url.
      responses:
        200:
          description: OK

definitions:
  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
      user_id:
        type: string
        description: Display name of 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: date
        desctipion: When this asset was published.