swagger.yaml

swagger: "2.0"
info:
  version: "v3"
  title: "Billing Account API"
# during production,should point to your server machine
host: localhost:3000
basePath: "/v3"
# during production, should use https
schemes:
- "http"
produces:
- application/json
consumes:
- application/json

securityDefinitions:
  Bearer:
    type: apiKey
    name: Authorization
    in: header

paths:
  /clients:
    get:
      tags:
        - client
      security:
        - Bearer: []
      operationId: findAllClients
      description: Retreive all clients, Admin user only.
      responses:
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '422':
          description: Invalid input
          schema:
            $ref: "#/definitions/ErrorModel"
        '200':
          description: A list of clients
          schema:
            $ref: "#/definitions/ClientListResponse"

    post:
      tags:
        - client
      security:
        - Bearer: []
      operationId: addNewClient
      description: Create a new client, Admin user only.
      parameters:
        - in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/NewClientBodyParam'
      responses:
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '201':
          description: Returns the newly created billing account
          schema:
            $ref: "#/definitions/ClientResponse"
        '422':
          description: Invalid input
          schema:
            $ref: "#/definitions/ErrorModel"


  /clients/{clientId}:
    get:
      tags:
        - client
      security:
        - Bearer: []
      description: Retrieve client by id, Admin user only.
      responses:
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '404':
          description: Not found
          schema:
            $ref: "#/definitions/ErrorModel"
        '200':
          description: a client
          schema:
            $ref: "#/definitions/ClientResponse"
      parameters:
        - $ref: "#/parameters/clientIdParam"
      operationId: getClientById

    patch:
      tags:
        - billingaccount
      security:
        - Bearer: []
      operationId: updateClient
      description: Update a client, Admin user only.
      responses:
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '404':
          description: Not found
          schema:
            $ref: "#/definitions/ErrorModel"
        '200':
          description: Successfully updated client. Returns updated client
          schema:
            $ref: "#/definitions/ClientResponse"
        '422':
          description: Invalid input
          schema:
            $ref: "#/definitions/ErrorModel"
        default:
          description: error payload
          schema:
            $ref: '#/definitions/ErrorModel'
      parameters:
        - $ref: "#/parameters/clientIdParam"
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/NewClientBodyParam"

  /billingaccounts:
    get:
      tags:
        - billingaccount
      security:
        - Bearer: []
      operationId: findBillingAccounts
      description: Retreive billing accounts that match the filter, Admin user only.
      responses:
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '400':
          description: Invalid input
          schema:
            $ref: "#/definitions/ErrorModel"
        '200':
          description: A list of billing accounts
          schema:
            $ref: "#/definitions/BillingAccountListResponse"
      parameters:
        - $ref: "#/parameters/offsetParam"
        - $ref: "#/parameters/limitParam"
        - name: filter
          required: true
          type: string
          in: query
          description: |
            Url encoded list of Supported filters
             - status
             - customer
             - user
             - startDate
             - endDate
        - name: sort
          required: false
          description: |
            sort billing accounts by status, name, startDate, endDate
          in: query
          type: string

    post:
      tags:
        - billingaccount
      security:
        - Bearer: []
      operationId: addBillingAccount
      description: Create a new billing account, Admin user only.
      parameters:
        - in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/NewBillingAccountBodyParam'
      responses:
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '201':
          description: Returns the newly created billing account
          schema:
            $ref: "#/definitions/BillingAccountResponse"
        '400':
          description: Invalid input
          schema:
            $ref: "#/definitions/ErrorModel"

  /billingaccounts/{billingAccountId}:
    get:
      tags:
        - billingaccount
      security:
        - Bearer: []
      description: Retrieve billing account by id, Admin user only.
      responses:
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '404':
          description: Not found
          schema:
            $ref: "#/definitions/ErrorModel"
        '200':
          description: a billing account
          schema:
            $ref: "#/definitions/BillingAccountResponse"
      parameters:
        - $ref: "#/parameters/billingAcountIdParam"
      operationId: getBillingAccount

    patch:
      tags:
        - billingaccount
      security:
        - Bearer: []
      operationId: updateBillingAccount
      description: Update a billing account, Admin user only.
      responses:
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '404':
          description: Not found
          schema:
            $ref: "#/definitions/ErrorModel"
        '200':
          description: Successfully updated billing account. Returns original and updated billing account object
          schema:
            $ref: "#/definitions/UpdateBillingAccountResponse"
        '400':
          description: Invalid input
          schema:
            $ref: "#/definitions/ErrorModel"
        default:
          description: error payload
          schema:
            $ref: '#/definitions/ErrorModel'
      parameters:
        - $ref: "#/parameters/billingAcountIdParam"
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/BillingAccountBodyParam"

  /billingaccounts/{billingAccountId}/users:
    get:
      tags:
        - billingaccount
      security:
        - Bearer: []
      description: Retrieve users of billing account, Admin user only.
      operationId: getBillingAccountUsers
      responses:
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '404':
          description: Not found
          schema:
            $ref: "#/definitions/ErrorModel"
        '200':
          description: users of billing account
          schema:
            $ref: "#/definitions/BillingAccountUserListResponse"
      parameters:
        - $ref: "#/parameters/billingAcountIdParam"

    post:
      tags:
        - billingaccount
      security:
        - Bearer: []
      description: Assign user to billing account, Admin user only.
      operationId: assignUserToBillingAccount
      responses:
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '404':
          description: Not found
          schema:
            $ref: "#/definitions/ErrorModel"
        '200':
          description: a billing account
          schema:
            $ref: "#/definitions/BillingAccountResponse"
      parameters:
        - $ref: "#/parameters/billingAcountIdParam"
        - in: body
          name: body
          required: true
          schema:
            type: object
            properties:
              userId:
                type: integer
                format: int64

  /billingaccounts/{billingAccountId}/users/{userId}:
    delete:
      tags:
        - billingaccount
      security:
        - Bearer: []
      description: Remove user from billing account, Admin user only.
      operationId: removeUserFromBillingAccount
      responses:
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '404':
          description: Not found
          schema:
            $ref: "#/definitions/ErrorModel"
        '204':
          description: successful operation
      parameters:
        - $ref: "#/parameters/billingAcountIdParam"
        - $ref: "#/parameters/userIdParam"

  /me/billingaccounts:
    get:
      tags:
        - billingaccount
      security:
        - Bearer: []
      operationId: findBillingAccountsByUser
      description: Retreive billing accounts that match the filter, For admin and non-admin user.
      responses:
        '403':
          description: No permission or wrong token
          schema:
            $ref: "#/definitions/ErrorModel"
        '400':
          description: Invalid input
          schema:
            $ref: "#/definitions/ErrorModel"
        '200':
          description: A list of billing accounts
          schema:
            $ref: "#/definitions/BillingAccountListResponse"
      parameters:
        - $ref: "#/parameters/offsetParam"
        - $ref: "#/parameters/limitParam"
        - name: filter
          required: true
          type: string
          in: query
          description: |
            Url encoded list of Supported filters
             - status
             - startDate
             - endDate
        - name: sort
          required: false
          description: |
            sort billing accounts by status, startDate, endDate
          in: query
          type: string


parameters:
  clientIdParam:
    name: clientId
    in: path
    description: client identifier
    required: true
    type: integer
    format: int64
  billingAcountIdParam:
    name: billingAccountId
    in: path
    description: billing account identifier
    required: true
    type: integer
    format: int64
  userIdParam:
    name: userId
    in: path
    description: user identifier
    required: true
    type: integer
    format: int64
  offsetParam:
    name: offset
    description: "number of items to skip. Defaults to 0"
    in: query
    required: false
    type: integer
    format: int32
  limitParam:
    name: limit
    description: "max records to return. Defaults to 10"
    in: query
    required: false
    type: integer
    format: int32

definitions:
  ResponseMetadata:
    title: Metadata object for a response
    type: object
    properties:
      totalCount:
        type: integer
        format: int64
        description: Total count of the objects

  ErrorModel:
    type: object
    properties:
      id:
        type: string
        description: unique id identifying the request
      version:
        type: string
      result:
        type: object
        properties:
          success:
            type: boolean
          status:
            description: http status code
            type: integer
            format: int32
          debug:
            type: object
          content:
            type: object

  NewClient:
    type: object
    required:
       - name
       - status
    properties:
      name:
        type: string
        description: The client name
      status:
        type: string
        description: the client status
      startDate:
        type: string
        description: billing account start date, Datetime (GMT)
      endDate:
        type: string
        description: billing account end date, Datetime (GMT)
      codeName:
        type: string
        description: the client code name

  NewBillingAccount:
    type: object
    required:
       - customerNumber
       - name
    properties:
      customerNumber:
        type: string
        description: customer number of billing account
      name:
        type: string
        description: billing account name
      status:
        type: string
        description: BillingAccount status
      startDate:
        type: string
        description: billing account start date, Datetime (GMT)
      endDate:
        type: string
        description: billing account end date, Datetime (GMT)

  NewBillingAccountBodyParam:
    type: object
    properties:
      param:
        $ref: "#/definitions/NewBillingAccount"

  NewClientBodyParam:
    type: object
    properties:
      param:
        $ref: "#/definitions/NewClient"

  BillingAccountBodyParam:
    type: object
    properties:
      param:
        $ref: "#/definitions/BillingAccount"

  Client:
    type: object
    properties:
      id:
        description: unique identifier
        type: integer
        format: int64
      name:
        type: string
        description: The client name
      status:
        type: string
        description: The client status
      startDate:
        type: string
        description: billing account start date, Datetime (GMT)
      endDate:
        type: string
        description: billing account end date, Datetime (GMT)
      codeName:
        type: string
        description: The client code name

  ClientResponse:
    title: Single client
    type: object
    properties:
      id:
        type: string
        description: unique id identifying the request
      version:
        type: string
      result:
        type: object
        properties:
          success:
            type: boolean
          status:
            type: string
          content:
            $ref: "#/definitions/Client"

  ClientListResponse:
    title: List response
    type: object
    properties:
      id:
        type: string
        readOnly: true
        description: unique id identifying the request
      version:
        type: string
      result:
        type: object
        properties:
          success:
            type: boolean
          status:
            type: string
          metadata:
            $ref: "#/definitions/ResponseMetadata"
          content:
            type: array
            items:
              $ref: "#/definitions/Client"

  BillingAccount:
    type: object
    properties:
      id:
        description: unique identifier
        type: integer
        format: int64
      customerNumber:
        type: string
        description: customer number of billing account
      name:
        type: string
        description: billing account name
      status:
        type: string
        description: billing account status
      startDate:
        type: string
        description: billing account start date, Datetime (GMT)
      endDate:
        type: string
        description: billing account end date, Datetime (GMT)
      amount:
        type: number
        format: float
        description: the challenge budget for this billing account.
      description:
        type: string
        description: the description for this billing account.
      poNumber:
        type: number
        format: int64
        description: the po number for this billing account.
      paymentTerms:
        type: string
        description: the payment terms for this billing account.
      subscriptionNumber:
        type: number
        format: float
        description: the subscription number for this billing account.
      createdAt:
        type: string
        description: Datetime (GMT) when task was created
        readOnly: true
      createdBy:
        type: integer
        format: int64
        description: READ-ONLY. User who created this task
        readOnly: true
      updatedAt:
        type: string
        description: READ-ONLY. Datetime (GMT) when task was updated
        readOnly: true
      updatedBy:
        type: integer
        format: int64
        description: READ-ONLY. User that last updated this task
        readOnly: true

  BillingAccountUser:
    type: object
    properties:
      id:
        description: unique identifier
        type: integer
        format: int64
      name:
        type: string
        description: billing account name
      description:
        type: string
        description: BillingAccount description

  BillingAccountResponse:
    title: Single billing account object
    type: object
    properties:
      id:
        type: string
        description: unique id identifying the request
      version:
        type: string
      result:
        type: object
        properties:
          success:
            type: boolean
          status:
            type: string
          content:
            $ref: "#/definitions/BillingAccount"

  UpdateBillingAccountResponse:
    title: response with original and updated billing account object
    type: object
    properties:
      id:
        type: string
        description: unique id identifying the request
      version:
        type: string
      result:
        type: object
        properties:
          success:
            type: boolean
          status:
            type: string
            description: http status code
          content:
            type: object
            properties:
              original:
                $ref: "#/definitions/BillingAccount"
              updated:
                 $ref: "#/definitions/BillingAccount"

  BillingAccountListResponse:
    title: List response
    type: object
    properties:
      id:
        type: string
        readOnly: true
        description: unique id identifying the request
      version:
        type: string
      result:
        type: object
        properties:
          success:
            type: boolean
          status:
            type: string
          metadata:
            $ref: "#/definitions/ResponseMetadata"
          content:
            type: array
            items:
              $ref: "#/definitions/BillingAccount"

  BillingAccountUserListResponse:
    title: List response
    type: object
    properties:
      id:
        type: string
        readOnly: true
        description: unique id identifying the request
      version:
        type: string
      result:
        type: object
        properties:
          success:
            type: boolean
          status:
            type: string
          metadata:
            $ref: "#/definitions/ResponseMetadata"
          content:
            type: array
            items:
              $ref: "#/definitions/BillingAccountUser"