openapi: 3.0.3
info:
  title: Device location API
  description: Service Enabling Network Function API for location verification
  termsOfService: http://swagger.io/terms/
  contact:
    email: project-email@sample.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 0.1.0
externalDocs:
  description: Product documentation at Camara
  url: https://github.com/camaraproject/
security:
  - oAuth2ClientCredentials: []
#  - BasicAuth: []
#  - apiKey: []
  - three_legged:
    - device-location-read
servers:
  - url: '{apiRoot}/{basePath}'
    variables:
      apiRoot:
        default: http://localhost:9091
        description: API root
      basePath:
        default: location/v0
        description: Base path for the device location API
paths:
  /verify:
    post:
      tags:
        - Location verification
      summary: 'Execute location verification for a user equipment'
      operationId: verifyLocation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyLocationRequest'
        required: true
      responses:
        '200':
          description: Location verification successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyLocationResponse'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
components:
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: '{tokenUrl}'
          scopes: {}
#    BasicAuth:
#      type: http
#      scheme: basic
#    apiKey:
#      type: apiKey
#      description: API key to authorize requests
#      name: apikey
#      in: query
    three_legged:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          scopes:
            device-location-read: Read device location
  schemas:
    VerifyLocationRequest:
      type: object
      properties:
        ueId:
          $ref: '#/components/schemas/UeId'
        uePort:
          $ref: '#/components/schemas/Port'
        latitude:
          $ref: '#/components/schemas/Latitude'
        longitude:
          $ref: '#/components/schemas/Longitude'
        accuracy:
          $ref: '#/components/schemas/Accuracy'
      required:
        - ueId
        - latitude
        - longitude
        - accuracy
    VerifyLocationResponse:
      type: object
      required:
        - verificationResult
      properties:
        verificationResult:
          $ref: '#/components/schemas/VerificationResult'
    UeId:
      description: User equipment identifier
      type: object
      properties:
        externalId:
          $ref: '#/components/schemas/ExternalId'
        msisdn:
          $ref: '#/components/schemas/MSISDN'
        ipv4Addr:
          $ref: '#/components/schemas/Ipv4Addr'
        ipv6Addr:
          $ref: '#/components/schemas/Ipv6Addr'
      minProperties: 1
    ExternalId:
      type: string
      example: '123456789@domain.com'
    MSISDN:
      type: string
      pattern: '^\+?[0-9]{5,15}$'
      example: '123456789'
      description: Subscriber number in E.164 format (starting with country code). Optionally prefixed with '+'.
    Ipv4Addr:
      type: string
      format: ipv4
      pattern: '^([01]?\d\d?|2[0-4]\d|25[0-5])(?:\.(?:[01]?\d\d?|2[0-4]\d|25[0-5])){3}(\/([0-9]|[1-2][0-9]|3[0-2]))?$'
      example: '192.168.0.1/24'
      description: |
        IPv4 address may be specified in form <address/mask> as:
          - address - an IPv4 number in dotted-quad form 1.2.3.4. Only this exact IP number will match the flow control rule.
          - address/mask - an IP number as above with a mask width of the form 1.2.3.4/24.
            In this case, all IP numbers from 1.2.3.0 to 1.2.3.255 will match. The bit width MUST be valid for the IP version.
    Ipv6Addr:
      type: string
      format: ipv6
      allOf:
        - pattern: '^((:|(0?|([1-9a-f][0-9a-f]{0,3}))):)((0?|([1-9a-f][0-9a-f]{0,3})):){0,6}(:|(0?|([1-9a-f][0-9a-f]{0,3})))(\/(([0-9])|([0-9]{2})|(1[0-1][0-9])|(12[0-8])))?$'
        - pattern: '^((([^:]+:){7}([^:]+))|((([^:]+:)*[^:]+)?::(([^:]+:)*[^:]+)?))(\/.+)?$'
      example: '2001:db8:85a3:8d3:1319:8a2e:370:7344'
      description: |
        IPv6 address, following IETF 5952 format, may be specified in form <address/mask> as:
          - address - The /128 subnet is optional for single addresses:
            - 2001:db8:85a3:8d3:1319:8a2e:370:7344
            - 2001:db8:85a3:8d3:1319:8a2e:370:7344/128
          - address/mask - an IP v6 number with a mask:
            - 2001:db8:85a3:8d3::0/64
            - 2001:db8:85a3:8d3::/64
    Port:
      type: integer
      minimum: 0
      maximum: 65535
      description: User equipment port. Device port may be required along with IP address to identify the target device
      example: 5060
    Latitude:
      description: Latitude component of location
      type: number
      format: double
      minimum: -90
      maximum: 90
      example: 50.735851
    Longitude:
      description: Longitude component of location
      type: number
      format: double
      minimum: -180
      maximum: 180
      example: 7.10066
    Accuracy:
      description: Accuracy expected for location verification in km
      type: number
      minimum: 2
      maximum: 200
      example: 50
    VerificationResult:
      description: Result of a verification request, true on match
      type: boolean
    ErrorInfo:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Code given to this error
        message:
          type: string
          description: Detailed error description
  responses:
    Generic400:
      description: Invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            code: INVALID_INPUT
            message: 'Invalid input'
    Generic401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            code: UNAUTHORIZED
            message: 'Authorization failed: ...'
    Generic403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            code: FORBIDDEN
            message: 'Operation not allowed: ...'
    Generic404:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            code: NOT_FOUND
            message: 'The specified resource is not found'
    Generic500:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            code: INTERNAL_SERVER_ERROR
            message: 'Internal server error'
    Generic503:
      description: Service unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            code: SERVICE_UNAVAILABLE
            message: 'Service unavailable'