openapi: 3.0.0
info:
  description: |
    Mobile operator lookup service.  

    # Introduction

    The API is used by different applications and services to know specified mobile number belong to which Operator.
    This service returns name of the Operator of the specified mobile number:
    Omantel, Ooredoo, Vodaphone etc.
    
  version: 1.0.0
  title: Mobile Operator Lookup Service
servers:
  - url: https://apigwsb.omantel.om
    variables:
      apiRoot:
        default: https://apigwsb.omantel.om
        description: API root
      basePath:
        default: /v1/mvnolookup
        description: Base path for the mobile operator lookup service
paths:
  /v1/mvnolookup/operator-lookup/{msisdn}:
    get:
      security:
        - oAuth2ClientCredentials: []
      tags:
        - lookup
      summary: Find Mobile Operator 
      operationId: operatorLookup
      description: |
        This operation is used to get name of the Mobile Operator
        to which specified mobile belongs to.
      parameters:
        - name: mock-key
          in: query
          description: The mock-key parameter is used to simulate different response scenarios. Choose one of the available keys. 
            **NOTE:- Mock keys are only applicable for sandbox environment and only give you mock responses.**
          required: true
          schema:
            type: string
            enum:
              - operator-lookup-get-200
              - operator-lookup-get-400
              - operator-lookup-get-401
              - operator-lookup-get-403
              - operator-lookup-get-404
              - operator-lookup-get-429
              - operator-lookup-get-500
              - operator-lookup-get-502
              - operator-lookup-get-503
              - operator-lookup-get-504
        - name: msisdn
          in: path
          description: Mobile number of the customer with country code. 
          required: true
          example: '96892500000'
          schema:
            type: string
            minLength: 8
            maxLength: 11            
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MVNOLookupResult"
        400:
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
        401:
          $ref: "#/components/responses/Generic401"
        403:
          $ref: "#/components/responses/Generic403"
        500:
          $ref: "#/components/responses/Generic500"
        503:
          $ref: "#/components/responses/Generic503"
        504:
          $ref: "#/components/responses/Generic504"
components:
  schemas:
    MVNOLookupResult:
      type: object
      required:
        - msisdn
      properties:
        msisdn:
          type: string
          description: Customer's Mobile Number
          example: "9689250xxxx"
        mobileOperatorName:
          type: string
          description: Name of the mobile operator of given mobile numer
          example: "Omantel"
        portInStatus:
          type: string
          description: Port-in status of the customer
    ErrorInfo:
      type: object
      required:
        - code
        - message
        - status
      properties:
        code:
          type: string
          description: Code given to this error
        status:
          type: string
          description: HTTP response status code
        message:
          type: string
          description: Detailed error description
    EventNotification:
      type: object
      description: Generic data type for event notification structure
      required:
        - event
      properties:
        eventSubscriptionid:
          type: string
          description: subscription identifier
        event:
          $ref: "#/components/schemas/Event"
    Event:
      type: object
      description: Generic data type for event structure
      required:
        - eventType
        - eventTime
        - eventDetail
      properties:
        eventid:
          type: string
          format: uuid
          description: Identifier of the event from the server where the event was reported
        eventType:
          type: string
          description: |
            Type of event. Different types considered so far:
            - `SmsInfo_COMPLETED`: Notification indication about SmsInfo completion.
            - `SmsInfo_FAILED`: Notification about SmsInfo failure.
        eventTime:
          type: string
          format: date-time
          description: Date time, in ISO-8601 extended local date format, when the event occurred. Time-offset from UTC may be used to match local OB time.
        eventDetail:
          $ref: "#/components/schemas/EventDetail"
    EventDetail:
      type: object
      description: Data type to provide event detail information
      properties:
        otlTransactionId:
          type: string
          description: Unique Identifier which was generated by Omantel
        clientCorrelatorId:
          type: string
          description: Client generated Unique Identifier of the SmsInfo
        status:
          type: string
          enum:
            - succeeded
            - failed
            - expired
          description: |
            Status of the procedure, according to `eventType` param. Possible status are:
            * `succeeded`: procedure was accomplished 
            * `failed`: procedure failed.
            * `expired`: delivery expired.
        description:
          type: string
          description: Description of the notification, both used when process was `succeeded` or `failed` indicating in the latter case human understable reason about why process failed.
        SmsInfoDate:
          type: string
          description: Date when the SmsInfo is effectively performed, both in 1-step and 2-step scenarios. This is a business information.
          format: date-time
      required:
        - otlTransactionId
        - clientCorrelatorId
        - status
        - description
  responses:
    Generic400:
      description: Invalid input
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: INVALID_ARGUMENT
            status: 400
            message: "Invalid MSISDN"
    Generic401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: UNAUTHORIZED
            status: 401
            message: "Authorization failed: ..."
    Generic403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: FORBIDDEN
            status: 403
            message: "Operation not allowed: ..."
    Generic404:
      description: Resource Not Found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: NOT_FOUND
            status: 404
            message: "The specified resource is not found"
    Generic409:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 409
            code: ALREADY_EXISTS
            message: "A specified resource duplicate entry found"
    Generic500:
      description: Server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: SERVER_ERROR
            status: 500
            message: "Server Error"
    Generic503:
      description: Service unavailable
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: SERVICE_UNAVAILABLE
            status: 503
            message: "Service unavailable"
    Generic504:
      description: Request timeout exceeded
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: REQUEST_TIMEOUT_EXCEEDED
            status: 504
            message: "Request timeout exceeded"
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://apigwsb.omantel.om/oauth2/accesstoken
          scopes: {}