Detroit REST-style API Proposal

[adhikasp]

Detroit REST-style API Proposal

This document will list and describe every API URL that will be provided by the Spring backend.

All API URL has /api prefix.

# User Resources

/users:
    GET:
        description: Get all user that registered on system
    POST:
        description: Create new user

/users/{userId}:
    GET:
        description: Get user profile that have id={userId}
    PATCH:
        description: Update user profile with id={userId}
    DELETE:
        description: Soft delete a user.

# Category and Parameter Resources

/categories:
    GET:
        description: Get all category, duh.
    POST:
        description: Create new category. Default weight is always 0%.
    PATCH:
        description: Edit existing category. Editing category must always
          edit all existing category at once. This to make sure 100% weight
          distribution could be verified server-side.
    DELETE:
        description: Soft delete a category.

/categories/{categoryId}:
    GET:
        description: Get category data and all of it's parameters.

/categories/{categoryId}/parameters :
    PATCH:
        description: Edit existing parameter. Editing parameter must always
          edit all existing parameter at once. This to make sure 100% weight
          distribution could be verified server-side.

/categories/{categoryId}/parameters/{parameterId}:
    POST:
        description: Create new parameter. Default weight is always 0%.
    DELETE:
        description: Soft delete a parameter.

# Review Resources

/reviews:
    GET:
        description: Get all review that created by currently authenticated 
          reviewer. If authenticated user is an admin, show all review in the 
          system.
    POST:
        description: Create new review of an agent from reviewer.

/reviews/{reviewId}:
    GET:
        description: Get detailed data of a review.
    PATCH:
        description: Update existing review.

/reviews/overview:
    GET:
        description: Get all review summary of all agent (for review summary 
          view).

/reviews/export:
    GET:
        description: Download all review data as excel file.
        parameters:
            - in: path
              name: exportType
              description: Specify type of export. Support `summary_export` and 
                `per_category_export`.
              required: true
              type: string
            - in: path
              name: startDate
              description: Start time of exported data
              required: true
              type: datetime
            - in: path
              name: endDate
              description: End time of exported data
              required: true
              type: datetime
            - in: path
              name: userList
              description: List of agent id that will be exported. 
                Can handle multiple agent in 1 export request. If this value 
                not provided or null, then export **all** agent data.
              required: false
              type: array of string
        responses:
            "200":
                description: Response with file content

# Statistics Resources

/statistics:
    GET:
        description: Get statistic data of all agent summary

/statistics/{agentId}:
    GET:
        description: Get statistic data of an agent with id={agentID}

/statistics/{agentId}/comments:
    GET:
        description: Get all comments of an agent with id={agentID}

# Model Definitions 

definitions:
    User:
        type: object
        properties:
            id:
                type: string
            fullname:
                type: string
            email:
                type: string
            role:
                type: string[]

TODO

• [x] Any missing API?
• [ ] Specify response and return data content.
• [ ] Specify authentication level needed for each endpoint (super admin, reviewer, or agent).
• [x] Rewrite in swagger-compliant file to generate a nice docs.

[adhikasp]

CC @DitoRaharjo

[adhikasp]

This is 100% swagger compliant

[adhikasp]

---
swagger: '2.0'
info:
  version: 1.0.0
  title: Project Detroit API
basePath: /v1
tags:
  - name: User
    description: Operation about user
  - name: Category
    description: Access to Detroit categories
  - name: Parameter
    description: Access to Detroit parameters
  - name: Review
    description: Operation about reviewing
  - name: Statistic
    description: Access to Detroit user's statistic
schemes:
  - http
paths:
  /users:
    get:
      tags:
        - User
      summary: Get all user that registered on system.
      parameters:
        - name: page
          in: query
          description: Active page number.
          required: false
          type: integer
        - name: size
          in: query
          description: Number of item per page.
          required: false
          type: integer
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/user'

    post:
      tags:
        - User
      summary: Create new user
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/user'
      responses:
        '200':
          description: OK

  /user/{user_id}:
    get:
      tags:
        - User
      summary: Get detailed data of a user
      parameters:
        - name: user_id
          in: path
          required: true
          type: integer
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/user'

    patch:
      tags:
        - User
      summary: Update a user data
      description: ""
      parameters:
        - name: user_id
          in: path
          required: true
          type: integer
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/user'
      responses:
        200:
          description: OK

    delete:
      tags:
        - User
      summary: Delete a user
      description: ""
      parameters:
        - name: user_id
          in: path
          required: true
          type: integer
      responses:
        200:
          description: OK

  /categories:
    get:
      summary: Get all category
      parameters:
        - name: page
          in: query
          description: page number.
          required: false
          type: number
          format: integer
        - name: size
          in: query
          description: Number of content per page.
          required: false
          type: number
          format: integer
        - name: sort_by
          in: query
          description: "Sorting criteria :
          \n - id (default)
          \n - name"
          required: false
          type: string
      tags:
        - Category
      responses:
        200:
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/category'

    post:
      tags:
        - Category
      summary: Add a new category
      description: ""
      operationId: addCategory
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: Category object that needs to be added
          required: false
          schema:
            $ref: "#/definitions/category"
      responses:
        "200":
          description: OK

    patch:
      tags:
        - Category
      summary: Update the categories
      description: ""
      operationId: updateCategory
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: Category object that needs to be added to the store
          required: true
          schema:
            type: array
            items:
              $ref: "#/definitions/category"
      responses:
        "200":
          description: OK

  /categories/{categoryId}:
    get:
      summary: Get category data and all of it's parameters.
      parameters:
        - in: path
          name: categoryId
          description: Category id to delete
          required: true
          type: integer
          format: int64
      tags:
        - Category
      responses:
        200:
          description: OK
          schema:
            type: object
            properties:
              id:
                type: integer
                format: int64
              name:
                type: string
                example: Technical
              description:
                type: string
                example: "Review for technical skill of agent"
              weight:
                type: integer
                example: 25
              bulk_status:
                type: boolean
                example: false
              is_active:
                type: boolean
                example: true
              parameters:
                type: array
                items:
                  $ref: '#/definitions/parameter'

    delete:
      tags:
        - Category
      summary: Soft delete a category.
      description: ""
      operationId: deleteCategory
      produces:
        - application/json
      parameters:
        - in: path
          name: categoryId
          description: Category id to delete
          required: true
          type: integer
          format: int64
      responses:
        "200":
          description: OK

  /categories/{categoryId}/parameters:
    post:
      tags:
        - Parameter
      summary: Create new parameter. Default weight is always 0%.
      description: ""
      operationId: addParameter
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: path
          name: categoryId
          description: Category ID
          required: true
          type: integer
          format: int64
        - in: body
          name: body
          description: Parameter object that needs to be added
          required: false
          schema:
            $ref: "#/definitions/parameter"
      responses:
        "200":
          description: OK

    patch:
      tags:
        - Parameter
      summary: "Edit existing parameter. Editing parameter must always
          edit all existing parameter at once. This to make sure 100% weight
          distribution could be verified server-side."
      description: ""
      operationId: updateParameter
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: path
          name: categoryId
          description: Category id for the parameter
          required: true
          type: integer
          format: int64
        - in: body
          name: body
          description: Parameter object that needs to be updated
          required: true
          schema:
            type: array
            items:
              $ref: "#/definitions/parameter"
      responses:
        "200":
          description: OK

  /categories/{categoryId}/parameters/{parameterId}:
    delete:
      tags:
        - Parameter
      summary: Soft delete a parameter.
      description: ""
      operationId: deleteParameter
      produces:
        - application/json
      parameters:
        - in: path
          name: categoryId
          description: Category id to delete
          required: true
          type: integer
          format: int64
        - in: path
          name: parameterId
          description: Parameter id to delete
          required: true
          type: integer
          format: int64
      responses:
        "200":
          description: OK

  /reviews:
    get:
      tags:
        - Review
      summary: Get review data summary
      description: Get all review that created by currently authenticated 
        reviewer. If authenticated user is an admin, show all review in the 
        system.
      parameters:
        - name: page
          in: query
          description: Active page number.
          required: false
          type: integer
        - name: size
          in: query
          description: Number of item per page.
          required: false
          type: integer
        - name: sort_by
          in: query
          description: Sorting criteria. Possible sort is by 
            id, nickname, fullname, team_leader, email, and channel.
          required: false
          type: string
      responses:
        200:
          description: OK

    post:
      tags:
        - Review
      summary: Create new review of an agent from reviewer.
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/review'
      responses:
        200:
          description: OK

  /reviews/{review_id}:
    get:
        tags:
          - Review
        summary: Get detailed data of a review.
        parameters:
          - name: review_id
            in: path
            type: integer
            required: true
        responses:
          200:
            description: OK
            schema:
              $ref: '#/definitions/review'

    patch:
        tags:
          - Review
        summary: Update existing review.
        parameters:
          - name: review_id
            in: path
            type: integer
            required: true
          - name: body
            in: body
            schema:
              $ref: '#/definitions/review'
        responses:
          200:
            description: OK

  /reviews/overview:
    get:
      tags:
        - Review
      summary: Get all review summary of all agent (for review summary 
        view).
      parameters:
        - name: page
          in: query
          description: Active page number.
          required: false
          type: integer
        - name: size
          in: query
          description: Number of item per page.
          required: false
          type: integer
        - name: sort_by
          in: query
          description: Sorting criteria. Possible sort is by 
            agent_name, review_daily_count, and review_cutoff_count.
          required: false
          type: string
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/ReviewOverview'

  /reviews/export:
    get:
      tags:
        - Review
      summary: Get exported review data as downloaded file.
      description: This will return a file data that contain all of review data in given range
        of time.
      parameters:
        - name: begin_date
          in: query
          required: true
          type: string
          format: datetime
        - name: end_date
          in: query
          required: true
          type: string
          format: datetime
        - name: agent_id
          in: query
          required: false
          type: array
          items:
            type: integer
        - name: export_type
          in: query
          required: true
          type: string
          description: Supported export type is `summary_export` and 
                `per_category_export`.

      responses: 
        200:
          description: OK. Return excel file.

  /statistics:
    get:
      summary: Get all statistic of all agent.
      parameters:
        - name: startDate
          in: query
          description: Filter of start date.
          required: false
          type: string
          format: datetime
        - name: endDate
          in: query
          description: Filter of end date.
          required: false
          type: string
          format: datetime
      tags:
        - Statistic
      responses:
        200:
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/statistic'

  /statistics/{agentId}:
    get:
      tags:
        - Statistic
      summary: Get statistic data of an agent with id={agentID}.
      parameters:
        - name: agentId
          in: path
          required: true
          type: integer
        - name: startDate
          in: query
          description: Filter of start date.
          required: false
          type: string
          format: datetime
        - name: endDate
          in: query
          description: Filter of end date.
          required: false
          type: string
          format: datetime
      responses:
        200:
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/statistic'

  /statistics/{agentId}/comments:
    get:
      tags:
        - Statistic
      summary: Get all comments of an agent with id={agentID}.
      parameters:
        - name: agentId
          in: path
          required: true
          type: integer
        - name: startDate
          in: query
          description: Filter of start date.
          required: false
          type: string
          format: datetime
        - name: endDate
          in: query
          description: Filter of end date.
          required: false
          type: string
          format: datetime
      responses:
        200:
          description: OK
          schema:
            type: array
            items:
              properties:
                date:
                  type: string
                  format: date-time
                  example: 12-02-2017
                value:
                  type: integer
                  example: 88
                comment:
                  type: string
                  example: "Untuk penanganan lebih baik jika lebih pelan temponya."
                casemgnt:
                  type: integer
                  example: 8

definitions:
  user:
    type: object
    properties:
      id:
        type: integer
      fullname:
        type: string
      nickname:
        type: string
      email:
        type: string
      channel:
        type: string
      team_leader:
        type: string
      date_of_birth:
        type: string
        format: date-time
      gender:
        type: string
      location:
        type: string
      phone_number:
        type: string

  category:
    type: object
    required:
      - name
      - weight
      - bulk_status
      - is_active
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
        example: Technical
      description:
        type: string
        example: "Review for technical skill of agent"
      weight:
        type: integer
        example: 25
      bulk_status:
        type: boolean
        example: false
      is_active:
        type: boolean
        example: true

  parameter:
    type: object
    required:
      - name
      - weight
      - category_id
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
        example: Technical
      description:
        type: string
        example: "Review for technical skill of agent"
      weight:
        type: integer
        example: 25
      category_id:
        type: integer
        example: 1

  review:
    type: object
    properties:
      reviewer:
        $ref: '#/definitions/user'
      agent:
        $ref: '#/definitions/user'
      customer_name:
        type: string
      casemgnt:
        type: integer
      category:
        type: string
      data:
        type: array
        items: 
          type: object
          properties:
            parameter:
              type: string
            value: 
              type: integer
            note:
              type: string

  ReviewOverview:
    type: object
    properties:
      agent:
        $ref: '#/definitions/user'
      categories:
        title: Category
        type: array
        items:
          type: object
          allOf: 
            - $ref: '#/definitions/category'
            - type: object
              properties:
                daily_count:
                  type: integer
                cutoff_count:
                  type: integer

  statistic:
    type: object
    required:
      - type
      - id
    properties:
      type:
        type: string
        example: Technical
      id:
        type: integer
        example: 1
      data:
        type: array
        items:
          type: object
          properties:
            date:
              type: string
              format: date
              example: 12-02-2017
            value:
              type: integer
              example: 88

[adhikasp]

See compiled swagger UI for easier reading.