swagger: "2.0"

info:
  version: "v1.5"
  title: MTN Customer Locations API
  description: An API to retrieve the Location details of an MTN customer. Please refer to the Response and Error Codes documents https://developers.mtn.com/insights/response-codes 

schemes:
  - https

host: "api.mtn.com"
basePath: "/v1"

consumes:
- "application/json"
produces:
- "application/json"

securityDefinitions:
  ApiKeyAuth:
    type: "apiKey"
    name: "X-API-Key"
    in: "header"     

security:
  - ApiKeyAuth: []

paths: 
    /customers/{customerId}/locations:
      get:
        description: "Retrieves the Location details of an MTN customer"
        summary: "View customer locations"
        operationId: "Retrieves the Location details of an MTN customer"
        tags:
          - "customers"
        parameters: 
        - name: "customerId"
          in: "path"
          description: "ID of the customer. It could be MSISDN, email address, or any other customer identifier. if id is msisdn, format must be E.123"
          required: true
          type: "string"
        responses:
          200:
            description: "Customer Locations object. For a successful request, the response will contain all the customers details. 
            If the customer does not have any requested data, then those fields will be null. E.g. if the customer does not any location set, then Country and Operator will be null."
            schema:
              $ref: "#/definitions/CustomerLocations"

          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"
            examples:
              The data object/envelope will be null:
                "data": null
          405:
            description: "Method Not allowed"
            schema:
              $ref: "#/definitions/Error"
          500:
            description: "Internal Server Error"
            schema:
              $ref: "#/definitions/Error"
    
     
definitions:
  Customer:
    type: "object"
    required: 
      - "customerId"
      - "_links"
    properties:
      customerId:
        type: "string"
      locations:
        type: "object"
        description: "The location of customer. Location includes Country and Network Operator"
        $ref: "#/definitions/CustomerLocations"
        
  CustomerLocations:
    type: "object"
    required: 
    - "_link"
    properties:
      data:
        type: "object"
        $ref: "#/definitions/Locations"
      _link:
        type: "string"
        description: "The link to retrieve the location of customer"
        $ref: "#/definitions/CustomerLinks"
        example: "https://api.mtn.com/v1/customers/27832000000/locations"
  
  Locations:
    type: "object"
    required:
    - "country"
    - "homeNetwork"
    - "operator"
    properties:
      country:
        type: "string"
        description: "The country that the customer MSISDN is currently located in, and could be roaming in. ISO 3166-1 short name format"
        example: "South Africa"
      homeNetwork:
        type: "string"
        description: "The country that the customer MSISDN was provisioned in. ISO 3166-1 short name format"
        example: "South Africa"
      operator:
        type: "string"
        description: "The network operator that the customer MSISDN is currently located in."
        enum:
        - "MTN"
        - "Other"
        - "null"
        example: "MTN"

  CustomerLinks:
    type: "object"
    required: 
    - "self"
    properties: 
      self:
        type: "object"
        required: 
        - "href"
        description: ""
        properties: 
          href:
            type: "string"
            description: ""

  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"