swagger.yaml

swagger: '2.0'
info:
  version: "1.0.0"
  title: Logistics Wizard Controller
  description: The main controller app for the Logistics Wizard system, interfacing with the ERP, Recommendations, and UI services.
  license:
    name: Apache 2.0
# the domain of the service
host: logistics-wizard.mybluemix.net
# array of all schemes that your API supports
schemes:
  - https
# will be prefixed to all paths
basePath: /api/v1
produces:
  - application/json
consumes:
  - application/json
paths:
  '/demos':
    post:
      summary: Create Demo
      description: |
        Create new demo session
      parameters:
        - name: demoInfo
          in: body
          description: Demo name and user email
          required: true
          schema:
            $ref: '#/definitions/Demo'
      tags:
        - Demo
      responses:
        201:
          description: The new Demo object
          schema:
            $ref: '#/definitions/Demo'
        422:
          description: Invalid email
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/demos/{guid}':
    get:
      summary: Get Demo
      description: |
        Retrieves the demo given the demo guid
      parameters:
        - name: guid
          in: path
          description: Demo guid
          required: true
          type: string
      tags:
        - User
      responses:
        200:
          description: The retrieved Demo object
          schema:
            $ref: '#/definitions/Demo'
        404:
          description: Demo does not exist
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    delete:
      summary: Delete Demo
      description: |
        Deletes a Demo given the demo guid
      parameters:
        - name: guid
          in: path
          description: Demo guid
          required: true
          type: string
      tags:
        - Demo
      responses:
        204:
          description: Demo deleted successfully
        404:
          description: Demo does not exist
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/demos/{guid}/retailers':
    get:
      summary: Get Demo retailers
      description: |
        Retrieves the retailers for a demo given the demo guid
      parameters:
        - name: guid
          in: path
          description: Demo guid
          required: true
          type: string
      tags:
        - Demo
        - Retailer
      responses:
        200:
          description: The retrieved Retailers
          schema:
            type: array
            items:
              $ref: '#/definitions/Retailer'
        404:
          description: Demo does not exist
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/demos/{guid}/users':
    post:
      summary: Create Demo User
      description: |
        Create new user for the demo given demo guid
      parameters:
        - name: guid
          in: path
          description: Demo guid
          required: true
          type: string
        - name: retailerId
          in: body
          description: ID of assigned retailer
          required: true
          schema:
            type: string
      tags:
        - Demo
        - User
      responses:
        201:
          description: The new User object
          schema:
            $ref: '#/definitions/User'
        400:
          description: Invalid input
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Demo or Retailer does not exist
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/demos/{guid}/login':
    post:
      summary: Sign In
      description: |
        Signs a specific user into a demo session
      parameters:
        - name: guid
          in: path
          description: Demo guid
          required: true
          type: string
        - name: userId
          in: body
          description: User ID
          required: true
          schema:
            type: string
      tags:
        - Demo
        - User
      responses:
        200:
          description: The bearer token
          schema:
            $ref: '#/definitions/AccessToken'
        404:
          description: Demo or User does not exist
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/logout/{token}':
    delete:
      summary: User Logout
      description: |
        Logs out the user with the corresponding bearer token
      parameters:
        - name: Authorization
          in: header
          description: Bearer token
          required: true
          type: string
        - name: token
          in: path
          description: Token of the user to be logged out
          required: true
          type: string
      tags:
        - User
      responses:
        204:
          description: Logout successful
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/admin':
    get:
      summary: Get initial demo data for logged in user
      description: |
        Retrieves data for the initial admin screen rendering
      parameters:
        - name: Authorization
          in: header
          description: Bearer token
          required: true
          type: string
      tags:
        - Shipment
        - Retailer
        - DistributionCenter
      responses:
        200:
          description: The retrieved demo session objects
          schema:
            $ref: '#/definitions/Session'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/shipments':
    get:
      summary: Retrieve shipments
      description: |
        Retrieves a list of all shipments for the supply chain managers
      parameters:
        - name: Authorization
          in: header
          description: Bearer token
          required: true
          type: string
        - name: status
          in: query
          description: Status of the shipments to be returned
          required: false
          type: string
        - name: did
          in: query
          description: Distribution center ID of the shipments to be returned
          required: false
          type: string
        - name: rid
          in: query
          description: Retailer ID of the shipments to be returned
          required: false
          type: string
      tags:
        - Shipment
      responses:
        200:
          description: An array of shipments
          schema:
            type: array
            items:
              $ref: '#/definitions/Shipment'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    post:
      summary: Create shipment
      description: |
        Create new shipment in the ERP system
      parameters:
        - name: shipment
          in: body
          description: ID of assigned retailer
          required: true
          schema:
            $ref: '#/definitions/Shipment'
      tags:
        - Shipment
      responses:
        201:
          description: The new Shipment object
          schema:
            $ref: '#/definitions/Shipment'
        400:
          description: Invalid input
          schema:
            $ref: '#/definitions/Error'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        422:
          description: Required data is absent or invalid
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/shipments/{id}':
    get:
      summary: Retrieve a single shipment from the ERP
      parameters:
        - name: Authorization
          in: header
          description: Bearer token
          required: true
          type: string
        - name: id
          in: path
          description: ID of the shipment to be retrieved
          required: true
          type: string
        - name: include_items
          in: query
          description: Boolean indicating whether to include LineItems in the returned shipment
          required: false
          type: string
      tags:
        - Shipment
      responses:
        200:
          description: Shipment retrieved successfully
          schema:
            $ref: '#/definitions/Shipment'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Shipment does not exist
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    delete:
      summary: Delete a shipment from the ERP
      parameters:
        - name: Authorization
          in: header
          description: Bearer token
          required: true
          type: string
        - name: id
          in: path
          description: ID of the shipment to be deleted
          required: true
          type: string
      tags:
        - Shipment
      responses:
        204:
          description: Shipment deleted successfully
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Shipment does not exist
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    put:
      summary: Update a shipment in the ERP
      parameters:
        - name: Authorization
          in: header
          description: Bearer token
          required: true
          type: string
        - name: id
          in: path
          description: ID of the shipment to be updated
          required: true
          type: string
        - name: data
          in: body
          description: The shipment object to replace the object currently associated with input ID
          required: false
          schema:
            $ref: '#/definitions/Shipment'
      tags:
        - Shipment
      responses:
        200:
          description: Shipment updated successfully
          schema:
            $ref: '#/definitions/Shipment'
        400:
          description: Invalid update to shipment
          schema:
            $ref: '#/definitions/Error'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Shipment does not exist
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/distribution-centers':
    get:
      summary: Retrieve distribution centers
      description: |
        Retrieves a list of distribution centers, only for the supply chain managers
      parameters:
        - name: Authorization
          in: header
          description: Bearer token
          required: true
          type: string
      tags:
        - DistributionCenter
      responses:
        200:
          description: Retrieved distribution centers successfully
          schema:
            type: array
            items:
              $ref: '#/definitions/DistributionCenter'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/distribution-centers/{id}':
    get:
      summary: Retrieve distribution center from the ERP
      parameters:
        - name: Authorization
          in: header
          description: Bearer token
          required: true
          type: string
        - name: id
          in: path
          description: ID of the distribution center to be retrieved
          required: true
          type: string
      tags:
        - DistributionCenter
      responses:
        200:
          description: Distribution center retrieved successfully
          schema:
            $ref: '#/definitions/DistributionCenter'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Distribution center does not exist
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/distribution-centers/{id}/shipments':
    get:
      summary: Retrieve shipments for a specific distribution center
      parameters:
        - name: Authorization
          in: header
          description: Bearer token
          required: true
          type: string
        - name: id
          in: path
          description: ID of the distribution center for which shipments are to be retrieved
          required: true
          type: string
        - name: status
          in: query
          description: Status of the shipments to be returned
          required: false
          type: string
      tags:
        - DistributionCenter
        - Shipment
      responses:
        200:
          description: Shipments retrieved successfully
          schema:
            $ref: '#/definitions/Shipment'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Distribution center does not exist
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/distribution-centers/{id}/inventory':
    get:
      summary: Retrieve inventory for a specific distribution center
      parameters:
        - name: Authorization
          in: header
          description: Bearer token
          required: true
          type: string
        - name: id
          in: path
          description: ID of the distribution center for which inventory is to be retrieved
          required: true
          type: string
      tags:
        - DistributionCenter
        - Inventory
      responses:
        200:
          description: Inventory retrieved successfully
          schema:
            type: array
            items:
              $ref: '#/definitions/Inventory'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Distribution center does not exist
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/retailers':
    get:
      summary: Retrieves retailers
      description: |
        Retrieves a list of all retailers, only for supply chain managers
      parameters:
        - name: Authorization
          in: header
          description: Bearer token
          required: true
          type: string
      tags:
        - Retailer
      responses:
        200:
          description: Retrieved retailers successfully
          schema:
            type: array
            items:
              $ref: '#/definitions/Retailer'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/retailers/{id}':
    get:
      summary: Retrieve retailer from the ERP
      parameters:
        - name: Authorization
          in: header
          description: Bearer token
          required: true
          type: string
        - name: id
          in: path
          description: ID of the retailer to be retrieved
          required: true
          type: string
      tags:
        - Retailer
      responses:
        200:
          description: Retailer retrieved successfully
          schema:
            $ref: '#/definitions/Retailer'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Retailer does not exist
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/retailers/{id}/shipments':
    get:
      summary: Retrieve shipments for a specific retailer
      parameters:
        - name: Authorization
          in: header
          description: Bearer token
          required: true
          type: string
        - name: id
          in: path
          description: ID of the retailer for which shipments are to be retrieved
          required: true
          type: string
        - name: status
          in: query
          description: Status of the shipments to be returned
          required: false
          type: string
      tags:
        - Retailer
        - Shipment
      responses:
        200:
          description: Shipments retrieved successfully
          schema:
            $ref: '#/definitions/Shipment'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Retailer does not exist
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/retailers/{id}/sales':
    get:
      summary: Retrieve sales data for a specific retailer
      parameters:
        - name: Authorization
          in: header
          description: Bearer token
          required: true
          type: string
        - name: id
          in: path
          description: ID of the retailer for which sales data is to be retrieved
          required: true
          type: string
      tags:
        - Retailer
      responses:
        200:
          description: Sales data retrieved successfully
          schema:
            type: array
            items:
              $ref: '#/definitions/SalesData'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Retailer does not exist
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/retailers/{id}/inventory':
    get:
      summary: Retrieve inventory for a specific retailer
      parameters:
        - name: Authorization
          in: header
          description: Bearer token
          required: true
          type: string
        - name: id
          in: path
          description: ID of the retailer for which inventory is to be retrieved
          required: true
          type: string
      tags:
        - Retailer
        - Inventory
      responses:
        200:
          description: Inventory retrieved successfully
          schema:
            type: array
            items:
              $ref: '#/definitions/Inventory'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Retailer does not exist
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/products':
    get:
      summary: Retrieves products
      description: |
        Retrieves all products distributed by the organization
      parameters:
        - name: Authorization
          in: header
          description: Bearer token
          required: true
          type: string
      tags:
        - Product
      responses:
        200:
          description: Retrieved products successfully
          schema:
            type: array
            items:
              $ref: '#/definitions/Product'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
definitions:
  Demo:
    properties:
      id:
        type: integer
        format: int32
      guid:
        type: string
      name:
        type: string
      createdAt:
        type: string
        format: date
      users:
        type: array
        items:
          $ref: '#/definitions/User'
    required:
      - name
  Session:
    properties:
      shipments:
        type: array
        items:
          $ref: '#/definitions/Shipment'
      distributionCenters:
        type: array
        items:
          $ref: '#/definitions/DistributionCenter'
      retailers:
        type: array
        items:
          $ref: '#/definitions/Retailer'
    required:
      - retailers
  User:
    properties:
      id:
        type: integer
        format: int32
      demoId:
        type: integer
        format: int32
      username:
        type: string
      email:
        type: string
      roles:
        type: array
        items:
          $ref: '#/definitions/Role'
      created:
        type: string
        format: date
      lastUpdated:
        type: string
        format: date
    required:
      - email
  Role:
    properties:
      id:
        type: string
      name:
        type: string
      created:
        type: string
        format: date
      modified:
        type: string
        format: date
    required:
      - name
  AccessToken:
    properties:
      token:
        type: string
    required:
      - token
    additionalProperties: false
  Product:
    properties:
      name:
        type: string
      id:
        type: integer
        format: int32
      supplierId:
        type: string
    required:
      - name
  Shipment:
    properties:
      status:
        default: NEW
        type: string
      createdAt:
        type: string
        format: date
      updatedAt:
        type: string
        format: date
      deliveredAt:
        type: string
        format: date
      estimatedTimeOfArrival:
        type: string
        format: date
      id:
        type: integer
        format: int32
      currentLocation:
        $ref: '#/definitions/Address'
      fromId:
        type: integer
        format: int32
      toId:
        type: integer
        format: int32
      items:
        type: array
        items:
          $ref: '#/definitions/LineItem'
    required:
      - status
      - createdAt
    additionalProperties: false
  Inventory:
    properties:
      quantity:
        default: 0
        type: number
        format: double
      id:
        type: integer
        format: int32
      productId:
        type: integer
        format: int32
      locationId:
        type: integer
        format: int32
      locationType:
        type: string
    additionalProperties: false
  LineItem:
    properties:
      quantity:
        default: 0
        type: number
        format: double
      id:
        type: integer
        format: int32
      shipmentId:
        type: integer
        format: int32
    required:
      - quantity
    additionalProperties: false
  DistributionCenter:
    properties:
      id:
        type: integer
        format: int32
      address:
        $ref: '#/definitions/Address'
      contact:
        $ref: '#/definitions/Contact'
      inventory:
        $ref: '#/definitions/Inventory'
    additionalProperties: false
  Retailer:
    properties:
      id:
        type: integer
        format: int32
      address:
        $ref: '#/definitions/Address'
      contact:
        $ref: '#/definitions/Contact'
    additionalProperties: false
  Address:
    properties:
      city:
        type: string
      state:
        type: string
      country:
        type: string
      latitude:
        type: number
        format: double
      longitude:
        type: number
        format: double
      id:
        type: integer
        format: int32
    additionalProperties: false
  Contact:
    properties:
      name:
        type: string
      id:
        type: integer
        format: int32
    required:
      - name
    additionalProperties: false
  SalesData:
    properties:
      productId:
        type: string
      sales:
        type: array
        items:
          $ref: '#/definitions/MonthlySales'
  MonthlySales:
    properties:
      month:
        type: string
      amount:
        type: integer
  Error:
    type: object
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      user_details:
        type: string
tags:
  - name: Supplier
  - name: Product
  - name: DistributionCenter
  - name: Shipment
  - name: Retailer
  - name: Inventory
  - name: User
  - name: Demo
  - name: Role