kwp-api-swagger.yaml

swagger: "2.0"
info:
  version: "1.0"
  title: "GPM Endpoints"
  description: >

    API follow the following conventions
      - GET: Retrieval of an object
      - POST: Upsert object

    Upon success, API return the expected payload as JSON and status 200 (or 204 if no
    payload).


    Upon error, API shall return status 4xx and error payload.
    
    
    The error payload should consists of the code, message, and description
    (refer to *ApiResponse* object), which will be displayed in a Popup Dialog in app.

paths:

  /panelist/{id}/points/current:
    get:
      description: "Retrieve latest points of a panelist. Current point balance is session-cached and cleared after inactive for a set period"
      tags:
      - Points
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "path"
        name: "id"
        description: "Panelist's unique identifier"
        required: true
        type: string
      responses:
        200:
          description: "Success"
          schema:
            $ref: "#/definitions/CurrentBalance"
          
  /panelist/{id}/points/statement:
    get:
      description: "Retrieve last-3 mth points statement of a panelist. Transaction list is session-cached and cleared after inactive for a set period"
      tags:
      - Points
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "path"
        name: "id"
        description: "Panelist's unique identifier"
        required: true
        type: string
      responses:
        200:
          description: "Success"
          schema:
            type: array
            items:
              $ref: "#/definitions/Transaction"
              
               
  /panelist/{id}/points/redeem:
    post:
      description: "deducting points from panelist's balance"
      tags:
      - Points
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "path"
        name: "id"
        description: "Panelist's unique identifier"
        required: true
        type: string
      - name: "transaction"
        description: "summary of the redemption"
        in: "body"
        required: true
        schema:
          $ref: '#/definitions/Transaction'
      responses:
        203:
          description: "Success"
        400:
          description: "Rejected"
          schema:
            $ref: "#/definitions/ApiResponse"
              
                  
           
  /panelist/{id}/profile:
    get:
      description: "Retrieve panelist's profile. Profile is session-cached and cleared after inactive for a set period"
      tags:
      - Profile
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "path"
        name: "id"
        description: "Panelist's unique identifier"
        required: true
        type: string
      responses:
        200:
          description: "Success"
          schema:
            $ref: "#/definitions/Panelist"
          
    post:
      description: "Update panelist's profile"
      tags:
      - Profile
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "path"
        name: "id"
        description: "Panelist's unique identifier"
        required: true
        type: string
      responses:
        203:
          description: "Success"
        400:
          description: "Rejected"
          schema:
            $ref: "#/definitions/ApiResponse"

          
  /panelists/{country}:
    get:
      description: "Retrieve updates on country's panelist after the specified date and store in our database."
      tags:
      - Sync
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "path"
        name: "country"
        description: "Country identifier"
        required: true
        type: string
      - name: "from"
        type: string
        in: "query"
        required: true
        description: "Fetch any changes after the provided datetime"
      responses:
        200:
          description: "Success"
          schema:
            type: array
            items:
              $ref: "#/definitions/Credentials"
        400:
          description: "Rejected"
          schema:
            $ref: "#/definitions/ApiResponse"

definitions:
  Panelist:
    type: "object"
    properties:
      id:
        type: "string"
      name:
        type: "string"
      phone:
        type: "string"
      email:
        type: "string"
        format: "email"
      address1:
        type: "string"
      address2:
        type: "string"
      postcode:
        type: "string"
      city:
        type: "string"
      state:
        type: "string"
      country:
        type: "string"
        
  Credentials:
    type: "object"
    description: "Represents the minimum required credentials to support the login and redeem operations. (TBD)"
    properties:
      id:
        type: "string"
      name:
        type: "string"

  CurrentBalance:
    type: "object"
    properties:
      points:
        type: "integer"
        format: "int32"
      last_update:
        type: "string"
        format: "date-time"
        
  Transaction:
    type: "object"
    description: "Represent a single point redeem / credit transaction"
    properties:
      points:
        type: "integer"
        format: "int32"
      transaction_time:
        type: "string"
        format: "date-time"
      transaction_description:
        type: "string"

  ApiResponse:
    type: object
    description: Describes an API call status or error
    properties:
      code:
        type: integer
        format: int32
        example: 100
      message:
        type: string
        example: Email or Password is invalid
      description:
        type: string
        example: Please enter the correct password