MTN Product Offering v2

# Example YAML to get you started quickly.
# Be aware that YAML has indentation based coping.
# Code completion support is available so start typing for available options.
swagger: '2.0'

# This is your document metadata
info:
  version: "0.0.2"
  title: MTN Product API
  description: |
    A MTN API that controls the display of the catalog of Products available for a customer to purchase.

host:
  www.api.mtn.com

schemes:
  - https

# Describe your paths here
paths:
  # This is a path endpoint. Change it.
  /products/{customerId}:
    get:
        description: "Retrieves the catalogue of Products available for purchase."
        summary: "View product catalogue."
        tags:
          - "products"
        parameters: 
        - name: "customerId"
          in: "path"
          description: "ID of the customer. It could be MSISDN, email address, or any other customer identifier"
          required: true
          type: "string"
        responses:
          200:
            description: "Product Catalogue object. For a successfull request, the response will contain all the products available. If a product type does not have any requested data, then those fields will be null. E.g. if the product type (e.g. Data) does not have products, then the data field will be an empty list."
            schema:
              $ref: "#/definitions/ProductCatalogue"
          400:
            description: "Bad Request"
            schema:
              $ref: "#/definitions/ErrorDefault"
          401:
            description: "Unauthorized"
            schema:
              $ref: "#/definitions/ErrorDefault"
          403:
            description: "Forbidden"
            schema:
              $ref: "#/definitions/ErrorDefault"
          404:
            description: "Customer not found"
            schema:
              $ref: "#/definitions/Error"
          405:
            description: "Method Not allowed"
            schema:
              $ref: "#/definitions/Error"
          500:
            description: "Internal Server Error"
            schema:
              $ref: "#/definitions/Error"
              
securityDefinitions:
  ApiKeyAuth:
    type: "apiKey"
    name: "X-API-Key"
    in: "header" 
    
definitions:
  ProductCatalogue:
    type: "object"
    required: 
      - "customerId"
      - "_links"
    properties:
      customerId:
        type: "string"
      data:
        type: "object"
        description: "the data envelope containing the voice, data and yolo information"
        $ref: "#/definitions/Data"
      
            
  Links:
    type: "object"
    required: 
    - "self"
    properties: 
      self:
        type: "object"
        required: 
        - "href"
        description: ""
        properties: 
          href:
            type: "string"
            description: ""
  Data:
    type: "object"
    properties:
      voice:
        type: "object"
        description: "the voice products available"
        $ref: "#/definitions/ProductFrequency"
      data:
        type: "object"
        description: "the data products available"
        $ref: "#/definitions/ProductFrequency"
      yolo:
        type: "object"
        description: "the yolo products available"
        $ref: "#/definitions/ProductFrequency"
            
  ProductFrequency:
    type: "object"
    required: 
    - "_link"
    properties:
      daily:
        type: "array"
        description: "The daily products of this type"
        items:
          $ref: "#/definitions/Product"
      weekly:
        type: "array"
        description: "The weekly products of this type"
        items:
          $ref: "#/definitions/Product"
      monthly:
        type: "array"
        description: "The monthly products of this type"
        items:
          $ref: "#/definitions/Product"
      _link:
        type: "string"
        description: "The link to retrieve the products for this type."
        $ref: "#/definitions/Links"
        example: "https://api.mtn.com/v1/products/27832000000?type=Voice"
        
  Product:
    type: "object"
    required:
    - "id"
    - "name"
    - "amount"
    description: "The product a customer can purchase."
    properties:
      id:
        type: "string"
        description: "Identifies the product. This must be the package ID from the catalogue."
        example: "97"
      name:
        type: "string"
        description: "The name of the product."
        example: "5,000Frw(7GB)/30Days"
      currency:
        type: "string"
        description: "ISO 4217 Three-letter ISO code for the currency."
        example: "RWF"
      amount:
        type: "string"
        description: "The amount that the product will cost"
        example: "5000"
      bundleCategory:
        type: "string"
        description: "The category of the bundle"
        example: "3G Bundles Daily"
      bundleType:
        type: "string"
        description: "The type of the bundle"
        example: "DataBundle"

  Error:
    properties:
      timestamp:
        type: "string"
        format: "date-time"
        description: "Error response code"
      status:
        type: "string"
        description: "Text explaining the reason for the error"
      error:
        type: "string"
      message:
        type: "string"
        description: "More error details and corrective measures"
      path:
        type: "string"
        description: ""
    
  ErrorDefault:
    properties:
      error:
        type: "string"
      error_description:
        type: "string"