Paris Comments API

comments_api.yml

swagger: '2.0'
info:
  title: Paris Comments API
  description: Provide virtual classroom feature for online education
  version: "1.0.0"
# the domain of the service
host: api.jumpcut.com
# array of all schemes that your API supports
schemes:
  - https
# will be prefixed to all paths
basePath: /comments
produces:
  - application/json
paths:
  /messages:
    get:
      description:
        Get messages associated to a certain channel
      parameters:
        - name: channel_id
          in: query
          description: retrieve single channel according to channel_id
          required: false
          type: string
        - name: media_id
          in: query
          description: retrieve messages according to media_id
          required: false
          type: string
        - name: month
          in: query
          description: retrieve messages according to month
          required: false
          type: string 
        - name: user_id
          in: query
          description: retrieve messages according to user_id
          type: string  
          required: false
        - name: sortType
          in: query
          type: string
          description: |
            *top* or *newest* or *oldest*
          required: false
        - name: type
          in: query
          description: Retrieve only the channels of certain genre
          required: false
          type: string
        - name: limit
          in: query
          description: Limit of the results. Used for pagination
          required: false
          type: integer
      tags:
        - Message
      responses:
        200:
          description: An array of Messages
          schema:
            $ref: '#/definitions/MessageWrapper'
        400:
          description: Malformatted request
        403:
          description: Unauthorized
        500:
          description: Server error, try again later
    post:
      description: |
        Create a new Message. To posted object should either contain the `channel_ids` or the `media_id` field.
      operationId: addMessage
      consumes:
       - application/json
      produces:
       - application/json
      tags:
        - Message
      parameters:
       - name: message
         in: body
         description: Message to add
         required: true
         schema:
           $ref: '#/definitions/MessageToInsert'
      responses:
       '200':
         description: Posted successfully.
         schema:
           $ref: '#/definitions/Message'
       '400':
         description: Malformatted request
       '403':
         description: Unauthorized
       '500':
         description: Server error, try again later
  /messages/{message_id}:
    get:
      description:
        Get a particular message
      parameters:
        - name: message_id
          in: path
          description: retrieve a single message according to message_id
          required: true
          type: string
      tags:
        - Message
      responses:
        200:
          description: a message
          schema:
            $ref: '#/definitions/Message'
        '403':
          description: Unauthorized
        '500':
          description: Server error, try again later
    patch:
      description:
        Perform useraction on the message, `update`, `vote`, `flat`. The token inside the cookies need to be present to perform this operation.
      operationId: patch
      consumes:
       - application/json
      produces:
       - application/json
      parameters:
       - name: message_id
         in: path
         description: id of the message to update
         required: true
         type: string

       - name: action
         in: body
         description: object
         required: true
         schema:
           $ref: '#/definitions/UserAction'

      tags:
        - Message
      responses:
       '200':
         description: Event is put successfully. Returned the updated message (Not supported yet)
         schema:
          $ref: '#/definitions/Message'
       '400':
         description: Malformatted request
       '403':
         description: Unauthorized
       '500':
         description: Server error, try again later
    put:
      description: |
        Perform a complete update of the message object. The message object posted is expected to contain all the fields
      operationId: put the message
      consumes:
       - application/json
      produces:
       - application/json
      parameters:
       - name: message_id
         in: path
         description: id of the message to update
         required: true
         type: string
       - name: message
         in: body
         description: object
         required: true
         schema:
           $ref: '#/definitions/Message'
      tags:
        - Message
      responses:
       '200':
         description: Event is put successfully. Returned the updated message (Not supported yet)
         schema:
          $ref: '#/definitions/Message'
       '400':
         description: Malformatted request
       '403':
         description: Unauthorized
       '500':
         description: Server error, try again later
    delete:
      description:
        Endpoint to delete a certain message. The token inside the cookies need to be present to perform this operation.
      operationId: deleteMessage
      parameters:
       - name: message_id
         in: path
         description: id of the message to delete
         required: true
         type: string
      tags:
        - Message
      responses:
       '200':
         description: Successfully deleted
       '400':
         description: Malformatted request
       '403':
         description: Unauthorized
       '500':
         description: Server error, try again later
  /channels:
    get:
      description: |
        The channel endpoint returns information about the *channel*. Provide either parent_id or ids (but not both) to get the channels.
      parameters:
        - name: parent_id
          in: query
          description: retrieve multiple channels according to its parent_id
          required: false
          type: string
        - name: ids
          in: query
          description: retrieve multiple channels in the same time
          required: false
          type: array
          items:
            type: string
        - name: genre
          in: query
          description: Retrieve only the channels of certain genre. Possible value "top", "sub", etc
          required: false
          type: string
        - name: type
          in: query
          description: Retrieve only the channels of certain type. Possible value "course", "video", "question", "groupchat", etc
          required: false
          type: string
        - name: limit
          in: query
          description: Limit of the results. Used for pagination
          required: false
          type: integer
          format: int32
        - name: lastEvaluatedKey
          in: query
          description: The lastEvaluatedKey returned by previous query. Use Json.stringify to convert to string and pass to the api. See $ref '#/definitions/LastEvalautedKeyForChannel'
          required: false
          type: string
      tags:
        - Channel
      responses:
        200:
          description: An array of channels
          schema:
            type: array
            items:
              $ref: '#/definitions/Channel'
        400:
          description: Malformatted request
        403:
          description: Unauthorized
        500:
          description: Server error, try again later
    post:
      summary: Create a new channel.
      description: |
        The channel endpoint for create a channel.
      operationId: addChannel
      consumes:
       - application/json
      produces:
       - application/json
      tags:
        - Channel
      parameters:
       - name: channel
         in: body
         description: Channel to add
         required: true
         schema:
           $ref: '#/definitions/ChannelToInsert'
      responses:
       '200':
         description: Event is posted successfully
       '400':
         description: Malformatted request
       '403':
         description: Unauthorized
       '500':
         description: Server error, try again later
  /channels/{channel_id}:
    get:
      summary: Get channel detail.
      description: |
        The channel endpoint returns information about the *channel*.
      parameters:
        - name: channel_id
          in: path
          description: retrieve single channel according to channel_id
          required: true
          type: string
      tags:
        - Channel
      responses:
        200:
          description: a channel
          schema:
            $ref: '#/definitions/Channel'
        '403':
          description: Unauthorized
        '500':
          description: Server error, try again later
    put:
      summary: (NOT SUPPORTED YET)
      description: |
        The channel endpoint for update a channel.
      operationId: updateChannel
      consumes:
       - application/json
      produces:
       - application/json
      parameters:
       - name: channel_id
         in: path
         description: id of the channel to update
         required: true
         type: string
       - name: channel
         in: body
         description: The channel
         required: true
         schema:
           $ref: '#/definitions/Channel'
      tags:
        - Channel
      responses:
       '200':
         description: Event is put successfully
         schema:
          $ref: '#/definitions/Channel'
       '400':
         description: Malformatted request
       '403':
         description: Unauthorized
       '500':
         description: Server error, try again later
    delete:
      summary:
        (NOT SUPPORTED YET)
      description:
        Endpoint to delete a certain channel
      operationId: deleteChannel
      parameters:
       - name: channel_id
         in: path
         description: id of the channel to delete
         required: true
         type: string
      tags:
        - Channel
      responses:
       '200':
         description: Successfully deleted
       '400':
         description: Malformatted request
       '403':
         description: Unauthorized
       '500':
         description: Server error, try again later
  /subscription:
    get:
      summary: (Not Supproted yet)
      description: |
        The endpoint to get subscription details
      parameters:
        - name: channel_id
          in: query
          description: Retrieve all subscritions associated with the channel. Either channel_id or user_id should be provided.
          required: false
          type: string
        - name: user_id
          in: query
          description: Retrieve all subscriptions associated with the user. Either channel_id or user_id should be provided.
          required: false
          type: string
        - name: genre
          in: query
          description: Retrieve only the subscriptions of certain genre
          required: false
          type: string
        - name: type
          in: query
          description: Retrieve only the subscriptions of certain type
          required: false
          type: string
      tags:
        - Subscription
      responses:
        200:
          description: An array of subscriptions
          schema:
            type: array
            items:
              $ref: '#/definitions/Subscription'
        400:
          description: Malformatted request
        403:
          description: Unauthorized
        500:
          description: Server error, try again later
    delete:
      summary: (Not Supproted yet)
      description:
        Endpoint to cancel a subscrition
      operationId: deleteSubscription
      parameters:
       - name: channel_id
         in: query
         description: id of the channel associated with the subscription
         required: true
         type: string
       - name: user_id
         in: query
         description: id of the user associated with the subscription
         required: true
         type: string
      tags:
        - Subscription
      responses:
       '200':
         description: Successfully deleted
       '400':
         description: Malformatted request
       '403':
         description: Unauthorized
       '500':
         description: Server error, try again later

definitions:
  ChannelToInsert:
    type: object
    properties:
      name:
        type: string
        description: Name of the channel.
      created_by:
        type: string
        description: The id of the user who created this channel
      type:
        type: string
        description: Type of the channel. Possible value "top", "sub".
      genre:
        type: string
        description: Genre of the channel. Possible value "course", "question", etc
      parent_id:
        type: string
        description: The id of the parent of this channel
  Channel:
    type: object
    properties:
      channel_id:
        type: string
        description: Unique identifier representing a specific channel
      created_at:
        type: string
        description: Timestamp for created_at
      updated_at:
        type: string
        description: Timestamp for edited_at
      name:
        type: string
        description: Name of the channel.
      created_by:
        type: string
        description: The id of the user who created this channel
      type:
        type: string
        description: Type of the channel. Possible value "top", "sub".
      genre:
        type: string
        description: Genre of the channel. Possible value "course", "question", etc
      parent_id:
        type: string
        description: The id of the parent of this channel
  Subscription:
    type: object
    properties:
      channel_id:
        type: string
        description: Unique identifier representing a specific channel
      user_id:
        type: string
        description: The user_id
      type:
        type: string
        description: The type of the channel. For filtering
      genre:
        type: string
        description: The genre of the channel. For filtering
      created_at:
        type: string
        description: The timestamp of created_at.
  MessageToInsert:
    type: object
    properties:
      channel_ids:
        type: array
        items:
          type: string
        description: Array of channel_ids that the message belongs to
      user_id:
        type: string
        description: The id of the user that creates this message
      type:
        type: string
        description: Possible value "text", "pdf", "image", etc
      parent_id:
        type: string
        description: The id of the parent message. For threaded comments in the future.
      text:
        type: string
        description: The normal text or description of the other media.
      urls:
        type: array
        items:
          type: string
        description: (Optional) Urls of the S3 resources.
      meta:
        type: string
        description: (Reserved for future use)
  UserAction:
    type: object
    properties:
      type:
        type: string
        description: |
          'vote' or 'flag' or 'update'
      value:
        type: string
        description: |
          only used together with type 'vote' and 'flag': '1' or '-1' or 'flag'
      direction:
        type: string
        description: |
          only used together with type 'vote' and 'flag': 'normal' or 'cancel'
      params:
        type: object
        properties:
          text:
            type: string
          approved:
            type: boolean
        description: |
          only used together with type 'update'; For now, only updating text is supported.
  LastEvaluatedKeyForChannel:
    type: object
    properties:
      parent_id:
        type: string
        description: The parent_id used for query. Necessary for pagination.
      channel_id:
        type: string
        description: The channel_id of the last item returned by the previous query
      deleted_created_at:
        type: string
        description: The deleted_created_at of the last item returned by the previous query
  MessageWrapper:
    type: object
    properties:
      Count:
        type: integer
        description: the count of the retuning object
      Items:
        type: array
        items:
          $ref: '#/definitions/Message'
      LastEvaluatedKey:
        type: object
        properties:
          channel_id:
            type: string
          deleted_depth_created_at_desc_message_id:
            type: string
          deleted_depth_created_at_asc_message_id:
            type: string
          deleted_depth_score_created_at_message_id:
            type: string
  Message:
    type: object
    properties:
      id:
        type: string
        description: The id of the message
      author_id:
        type: string
        description: user_id of the current user
      channel_id:
        type: string
        description: The id of the channel the message belongs to.
      parent_id:
        type: string
        description: The id of the parent message. For threaded comments in the future.  
      message:
        type: string
        description: The normal text or description of the comment.
      media:
        type: array
        items:
          type: object
          description: The individual medias/images
          properties:
            id:
              type: number
              description: The primary key for the image
            directory:
              type: string
              description: The directory in which it gets stored
            full:
              type: string
              description: URL of the full-sized image
            key:
              type: string
              description: Key which identifies the image
            medium:
              type: string
              description: URL of the medium-sized image
            original:
              type: string
              description: URL of the original-sized image
            small:
              type: string
              description: URL of the small-sized image
      vote:
        type: array
        items:
          type: object
          description: Upvotes/downvotes for the specific comment
          properties:
            id:
              type: number
              description: The primary key for the vote
            user_id:
              type: string
              description: The primary key for the user who voted
            value:
              type: number
              description: either of +1/-1
      flag:
        type: array
        items:
          type: object
          description: For reporting/flagging the comment
          properties:
            id:
              type: number
              description: The primary key for the flag
            user_id:
              type: string
              description: The primary key for the user who flagged the comment
            status:
              type: boolean
              description: true/false
      activity:
        type: number
        description: to make the comment hidden/disabled
      created_at:
        type: string
        description: Timestamp of the created_at
      updated_at:
        type: string
        description: Timestamp of the edited_at
      deleted_at:
        type: string
        description: Timestamp of the deleted_at