OPENDC(Jigum) API

swagger.yaml

swagger: '2.0'
info:
  title: Jigum API
  description: ...
  version: "0.1.0"
host: api.foo.com
schemes:
  - https
basePath: /v1
produces:
  - application/json
parameters:
  target:
    name: target
    description: Type of data
    in: path
    required: true
    type: string
    enum:
      - keyword
      - post
      - all
  targetId:
    name: targetId
    description: Keyword or Uuid of the post.
    in: path
    required: true
    type: string
    maxLength: 255
  keyword:
    name: keyword
    in: path
    required: true
    type: string
    maxLength: 255
  id:
    name: id
    description: target uuid
    in: path
    required: true
    type: string
    format: uuid
  size:
    name: size
    description: Size of the list.
    in: query
    required: false
    type: integer
    format: int32
    default: 5
    minimum: 1
    maximum: 100
  before:
    name: before
    description: Datetime for paging
    in: query
    required: false
    type: string
    format: date-time

responses:
  200:
    description: OK
  400:
    description: Unexpected error.
    schema:
      $ref: '#/definitions/Error'
    
paths:
  /keyword/{keyword}:
    get:
      summary: Get keyword information
      parameters:
        - $ref: '#/parameters/keyword'
      responses:
        200:
          description: Keyword Model
          schema:
            $ref: '#/definitions/Keyword'
        400: 
          $ref: '#/responses/400'
  /posts/{filter}/{target}/{targetId}:
    get:
      summary: Post List
      description: |
        This endpoint returns list of post about a given keyword.
        The response includes details about all of posts.
        If 'Popular Keyword Posts' is requested, returns all of the posts.
        If 'Recent Keyword Posts' is requested, returns requested size of the posts.
        If 'Popular Post Comments' is requested, returns all of the comments.
        If 'Recent Post Comments' is requested, returns requested size of the comments.
      parameters:
        - name: filter
          description: Method to order lists.
          in: path
          required: true
          type: string
          enum: 
            - popular
            - recent
            - official
        - $ref: '#/parameters/target'
        - $ref: '#/parameters/targetId'
        - $ref: '#/parameters/size'
        - $ref: '#/parameters/before'
      responses:
        200:
          description: An array of posts.
          schema: 
            type: array
            items:
              $ref: '#/definitions/Post'
        400:
          $ref: '#/responses/400'
  /post/{id}:
    get:
      summary: Get details of the post
      description: |
        This endpoint returns the post about a given id.
        The response includes all of details of the post.
      parameters:
        - $ref: '#/parameters/id'
      responses:
        200:
          description: A details of the post.
          schema:
            $ref: '#/definitions/Post'
        400:
          $ref: '#/responses/400'
    put:
      summary: Update the post
      consumes:
        - multipart/form-data
      security:
        - deviceKey: []
      parameters:
        - name: id
          description: Id of the post
          in: path
          required: true
          type: string
          format: uuid
        - name: links
          description: Array of links.
          in: formData
          required: false
          type: array
          items: 
            type: string
            format: url
        - name: images
          description: Array of images.
          in: formData
          required: false
          type: array
          items:
            type: string
            format: url
        - name: text
          description: Text user input.
          in: formData
          required: false
          type: string
        - name: isOfficial
          in: formData
          required: false
          type: boolean
      responses:
        200:
          description: A details of the updated post.
          schema:
            $ref: '#/definitions/Post'
        400:
          $ref: '#/responses/400'
    delete:
      summary: Delete the post
      security:
        - deviceKey: []
      parameters:
        - name: id
          description: Id of the post
          in: path
          required: true
          type: string
          format: uuid
      responses:
        200:
          $ref: '#/responses/200'
        400:
          $ref: '#/responses/400'
  /post:
    post:
      summary: New post
      consumes:
        - multipart/form-data
      security:
        - deviceKey: []
      parameters:
        - name: parent
          description: Id of parent post. (optional)
          in: formData
          required: false
          type: string
          format: uuid
        - name: links
          description: Array of links.
          in: formData
          required: false
          type: array
          items: 
            type: string
            format: url
        - name: images
          description: Array of images.
          in: formData
          required: false
          type: array
          items:
            type: string
            format: url
        - name: text
          description: Text user input.
          in: formData
          required: false
          type: string
        - name: isOfficial
          in: formData
          required: false
          type: boolean

      responses:
        200:
          description: A details of the new post.
          schema:
            $ref: '#/definitions/Post'
        400:
          $ref: '#/responses/400'
  /device/auth/request:
    post:
      summary: Request a sms with the captcha token.
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - name: phone
          description: User's phone number.
          in: formData
          required: true
          type: string
          format: tel
        - name: captcha
          description: Token of the captcha.
          in: formData
          required: true
          type: string
          format: uuid
      responses:
        200:
          $ref: '#/responses/200'
        400:
          $ref: '#/responses/400'
  /device/auth/verify:
    post:
      summary: Request a new deviceKey.
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - name: phone
          description: User's phone number.
          in: formData
          required: true
          type: string
          format: tel
        - name: captcha
          description: Token of the previous operation.
          in: formData
          required: true
          type: string
          format: uuid
        - name: smscode
          description: Sms code the user received.
          in: formData
          required: true
          type: integer
          format: int32
      responses:
        200:
          description: New device key
          schema:
            type: object
            properties:
              deviceKey:
                type: string
                format: uuid
        400:
          $ref: '#/responses/400'
  /devices/my:
    get:
      summary: My device list
      security:
        - deviceKey: []
      responses:
        200: 
          description: Device List
          schema:
            type: array
            items:
              properties:
                deviceId:
                  type: string
                  format: uuid
                lastContact:
                  type: string
                  format: date-time
                userAgent:
                  type: string
                ipAddr:
                  type: string
        400:
          $ref: '#/responses/400'
  /device/{id}:
    delete:
      summary: Disconnet the device.
      security:
        - deviceKey: []
      parameters:
        - $ref: '#/parameters/id'
      responses:
        200:
          $ref: '#/responses/200'
        400:
          $ref: '#/responses/400'        
  /groups:
    get:
      summary: |
        Available list of groups.
        Use when list ranks.
      responses:
        200:
          $ref: '#/responses/200'
        400:
          $ref: '#/responses/400'
  /group/my:
    put:
      summary: Set my group.
      consumes:
        - application/x-www-form-urlencoded
      security:
        - deviceKey: []
      parameters:
        - name: group
          description: Id of the desired group.
          in: formData
          required: true
          type: string
          format: uuid
      responses:
        200:
          $ref: '#/responses/200'
        400:
          $ref: '#/responses/400'
  /vote/{direction}/{target}/{targetId}:
    post:
      summary: Vote for something.
      consumes:
        - application/x-www-form-urlencoded
      security:
        - deviceKey: []
      parameters:
        - name: direction
          description: Up or Down
          in: path
          required: true
          type: string
          enum:
            - up
            - down
        - $ref: '#/parameters/target'
        - $ref: '#/parameters/targetId'
      responses:
        200:
          $ref: '#/responses/200'
        400:
          $ref: '#/responses/400'
  /votes/my/{target}:
    get:
      summary: My recent votes. (For sync on multiple devices)
      security:
        - deviceKey: []
      parameters:
        - $ref: '#/parameters/target'
        - $ref: '#/parameters/size'
        - $ref: '#/parameters/before'
      responses:
        200:
          description: Votes.
          schema:
            type: array
            items:
              $ref: '#/definitions/Vote'
        
        400:
          $ref: '#/responses/400'
  /report-abuse/{target}/{targetId}:
    post:
      summary: Report the abused content.
      consumes:
        - application/x-www-form-urlencoded
      security:
        - deviceKey: []
      parameters:
        - $ref: '#/parameters/target'
        - $ref: '#/parameters/targetId'
      responses:
        200:
          $ref: '#/responses/200'
        400:
          $ref: '#/responses/400'



definitions:
  Post:
    properties:
      id:
        type: string
        format: uuid
        description: Unique identifier representing a specific post.
      parentKeyword:
        type: string
      parentPost:
        $ref: '#/definitions/Post'
      isOfficial:
        type: boolean
        description: Is this the official post/comment ?
      author:
        $ref: '#/definitions/User'
      links:
        type: array
        items:
          $ref: '#/definitions/Link'
      images:
        type: array
        items:
          $ref: '#/definitions/Image'
      text:
        type: string
        description: This may be plain text or html by client.
      countVotes:
        type: integer
        format: int32
        description: Votes point. Denormalized value. It may be less than zero.
      countComments:
        type: integer
        format: int32
        description: Count of comments.
      createdAt: 
        type: string
        format: date-time
        description: Datetime post created at.
  Image:
    properties:
      url:
        type: string
        format: url
        description: Url of the image. Server returns the best size and type for the current client.
      width:
        type: integer
        format: int32
        description: Width of the image.
      height:
        type: integer
        format: int32
        description: Height of the image.
  Link:
    properties:
      host:
        type: string
        format: url
        description: Domain of host site.
      hostName:
        type: string
        description: Name of host site.
      hostLogo:
        type: string
        format: url
        description: Image of host logo.
      url:
        type: string
        format: url
        description: Link url. The server provides the appropriate url for each device.
      title:
        type: string
        description: Webpage title.
      description:
        type: string
        description: Webpage description.
      thumbnail:
        type: string
        format: url
        description: Webpage thumbnail.
  User:
    properties:
      id:
        type: string
        format: uuid
        description: Unique identifier representing a specific user.
      name:
        type: string
        description: Name of the user.
      photo:
        $ref: '#/definitions/Image'
      badges:
        type: array
        items:
          properties:
            name:
              type: string
            icon:
              type: string
              format: url
      jobs: 
        type: array
        items:
          properties:
            name:
              type: string
  Vote:
    properties:
      createdAt:
        type: string
        format: date-time
      type:
        type: string
        enum:
          - keyword
          - post
      id:
        type: string
        description: Keyword or the id of the post.
      direction:
        type: string
        enum:
          - up
          - down
  Keyword:
    properties:
      countVotes:
        type: integer
        format: int32
        description: Votes point. Denormalized value. It may be less than zero.
      countAbuseReports:
        type: integer
        format: int32
      
  Error:
    properties:
      code:
        type: string
      message:
        type: string
      target:
        type: string
        
securityDefinitions:
  deviceKey:
    type: apiKey
    name: deviceKey
    in: header