openapi: 3.0.3
info:
  title: Global System for Mobile Communications GSMA Camara Project Application Endpoint Discovery API
  version: 0.1.0-wip
  description: >-
    The Application Discovery API extends beyond the capabilities of the Simple
    Edge Discovery API by not only locating the nearest Edge Cloud Zone but also
    directly linking to the application endpoints within those Edge Cloud Zones.
  contact:
    email: sp-edc@lists.camaraproject.org
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
externalDocs:
  description: Product documentation at CAMARA.
  url: https://github.com/camaraproject/EdgeCloud
servers:
  - url: '{apiRoot}/{basePath}'
    variables:
      apiRoot:
        default: https://localhost:443
        description: API root.
      basePath:
        default: application-endpoint-discovery/vwip
        description: Base path for the Application Endpoint Discovery.
tags:
  - name: Discovery
paths:
  /app-endpoints:
    get:
      security:
        - openId:
            - application-endpoint-discovery:app-endpoints:read
      operationId: getAppEndpoints
      parameters:
        - name: filter
          in: query
          required: true
          description: |
            Filter the Edge Cloud Zones according to the parameter value.
            For this API the only supported value is `closest`.
          schema:
            type: string
            enum:
              - closest
        - name: IPv4-Address
          in: header
          required: false
          description: The public IPv4 address allocated to the device.
          example: 84.125.93.10
          schema:
            $ref: '#/components/schemas/SingleIpv4Addr'
        - name: IPv6-Address
          in: header
          required: false
          description: The public IPv6 address allocated to the device.
          example: 2001:db8:85a3:8d3:1319:8a2e:370:7348
          schema:
            $ref: '#/components/schemas/DeviceIpv6Address'
        - name: Network-Access-Identifier
          in: header
          description: |
            3GPP network access identifier for the subscription
            being used by the device.
          example: 4d596ac1-7822-4927-a3c5-d72e1f922c94@domain.com
          required: false
          schema:
            $ref: '#/components/schemas/NetworkAccessIdentifier'
        - name: Phone-Number
          in: header
          example: '+441234567890'
          required: true
          description: |
            MSISDN in E.164 format (starting with country code) of
            the mobile subscription being used by the device. Optionally
            prefixed with '+'.
          schema:
            $ref: '#/components/schemas/PhoneNumber'
        - name: AppId
          in: header
          required: true
          description: |
            A globally unique identifier associated with the application.
            OP generates this identifier when the application is submitted over
            NBI.
          schema:
            $ref: '#/components/schemas/AppId'
        - name: X-Correlator
          in: header
          required: false
          description: |
            When the API Consumer includes the "X-Correlator" header in the
            request, the API provider must include it in the response with
            the same value that was used in the request. Otherwise, it is
            optional to include the "X-Correlator" header in the response with
             any valid value. Recommendation is to use UUID for values.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: |
            Successful response, returning the closest App Instance Endpoint
            Zone to the user device identified in the request header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessEndpoints'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '405':
          $ref: '#/components/responses/405MethodNotAllowed'
        '406':
          $ref: '#/components/responses/406Unacceptable'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
        '502':
          $ref: '#/components/responses/502BadGateway'
        '503':
          $ref: '#/components/responses/503ServiceUnavailable'
        '504':
          $ref: '#/components/responses/504GatewayTimeout'
      tags:
        - Discovery
      summary: |-
        Global System for Mobile Communications Returns the Endpoint of the closest App Instance to user device
        identified in the request.
      description: |
        On receiving this request, the network will return the name
        of the App Instance with the shortest network path to the end user
        device identified in the request.
components:
  securitySchemes:
    openId:
      description: OpenID Provider Configuration Information.
      type: openIdConnect
      openIdConnectUrl: .well-known/openid-configuration
  headers:
    X-Correlator:
      description: |
        When the API Consumer includes the "X-Correlator" header in the request,
         the API provider must include it in the response with the same value t
         hat was used in the request. Otherwise, it is optional to include the
         "X-Correlator" header in the response with any valid value.
         Recommendation is to use UUID for values.
      required: false
      schema:
        type: string
        format: uuid
  schemas:
    AppId:
      type: string
      format: uuid
      description: >-
        A globally unique identifier associated with the application. This GUID
        will have been previously provided by the Edge Cloud Zone provider.
    AccessEndpoints:
      type: object
      description: |
        Application Endpoint for an especific instance that is
        running in an specific Edge Cloud Zone.
      required:
        - port
      anyOf:
        - required:
            - fqdn
        - required:
            - ipv4Addresses
        - required:
            - ipv6Addresses
      properties:
        port:
          $ref: '#/components/schemas/Port'
        fqdn:
          $ref: '#/components/schemas/Fqdn'
        ipv4Addresses:
          description: IP version 4 of an application instance.
          type: array
          items:
            $ref: '#/components/schemas/Ipv4Addr'
          minItems: 1
        ipv6Addresses:
          description: IP version 6 of an application instance.
          type: array
          items:
            $ref: '#/components/schemas/Ipv6Addr'
          minItems: 1
    ErrorResponse:
      description: Error code and human-readable description.
      type: object
      properties:
        code:
          type: string
          description: A short, human-readable summary of the problem type.
        status:
          type: integer
          description: The HTTP status code.
        message:
          type: string
          description: |
            This parameter appears when there is an error.
            A human readable explanation specific to this occurrence of the
            problem.
    Fqdn:
      type: string
      description: Fully Qualified Domain Name.
    Ipv4Addr:
      type: string
      description: |
        IP of the device. A single IPv4 address may be specified in
        dotted-quad form 1.2.3.4. Only this exact IP number will match the flow
        control rule.
      example: 198.51.100.1
    Ipv6Addr:
      type: string
      description: |
        IP of the device. A single IPv6 address, following IETF 5952
        format, may be specified like 2001:db8:85a3:8d3:1319:8a2e:370:7344
      example: 2001:db8:85a3::8a2e:370:7334
    Port:
      type: integer
      description: Port to stablish the connection
      minimum: 0
    PhoneNumber:
      description: |
        A public identifier addressing a telephone subscription.
        In mobile networks it corresponds to the MSISDN (Mobile Station
        International Subscriber Directory Number). In order to be globally
        unique it has to be formatted in international format, according
        to E.164 standard, prefixed with '+'.
      type: string
      pattern: ^\+[1-9][0-9]{4,14}$
      example: '+123456789'
    NetworkAccessIdentifier:
      description: |
        A public identifier addressing a subscription in a mobile
        network. In 3GPP terminology, it corresponds to the GPSI formatted with
        the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike
        the telephone number, the network access identifier is not subjected to
        portability ruling in force, and is individually managed by each
        operator.
      type: string
      example: 123456789@domain.com
    SingleIpv4Addr:
      description: |
        A single IPv4 address with no subnet mask
      type: string
      format: ipv4
      example: 84.125.93.10
    DeviceIpv6Address:
      description: |
        The device should be identified by the observed IPv6 address, or by any
        single IPv6 address from within the subnet allocated to the device
        (e.g. adding ::0 to the /64 prefix).
      type: string
      format: ipv6
      example: 2001:db8:85a3:8d3:1319:8a2e:370:7344
  responses:
    400BadRequest:
      description: Bad Request
      headers:
        X-Correlator:
          $ref: '#/components/headers/X-Correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            InsufficientParameters:
              description: |
                Sufficient parameters must be specified to allow the
                target UE to be identified.
              value:
                code: INVALID_ARGUMENT
                status: 400
                message: >-
                  Insufficient parameters: At least one of
                  Network-Access-Identifier, Phone-Number or IP-Address must be
                  specified, or, the API must be called by a client on a
                  network-attached device (hence passing the source IP in the
                  request header).
            InvalidExternalId:
              value:
                code: INVALID_ARGUMENT
                status: 400
                message: 'Invalid Header Format: Network-Access-Identifier'
            InvalidMSISDN:
              value:
                code: INVALID_ARGUMENT
                status: 400
                message: 'Invalid Header Format: Phone-Number'
            InvalidIP:
              description: |
                This error will be returned if the IP address does
                not have a valid format, or if the IP address is a private IPv4
                address.
              value:
                code: INVALID_ARGUMENT
                status: 400
                message: 'Invalid Header Format: IP-Address'
    401Unauthorized:
      description: Unauthorized
      headers:
        X-Correlator:
          $ref: '#/components/headers/X-Correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            InvalidCredentials:
              value:
                code: UNAUTHENTICATED
                status: 401
                message: >-
                  Request not authenticated due to missing, invalid, or expired
                  credentials
    403Forbidden:
      description: Forbidden
      headers:
        X-Correlator:
          $ref: '#/components/headers/X-Correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            InsufficientPermissions:
              value:
                code: PERMISSION_DENIED
                status: 403
                message: >-
                  Client does not have sufficient permissions to perform this
                  action
    404NotFound:
      description: Not Found
      headers:
        X-Correlator:
          $ref: '#/components/headers/X-Correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            SubscriberNotFound:
              description: |
                No device found for the specified parameters,
                meaning the closest Edge Cloud Zone cannot be determined.
              value:
                code: NOT_FOUND
                status: 404
                message: No device found for the specified parameters
            EndpointNotFound:
              description: |
                No endpoint instance found for the specified parameters,
                meaning the closest Edge Cloud Zone cannot be determined.
              value:
                code: NOT_FOUND
                status: 404
                message: No endpoint instance found for the specified parameters
    405MethodNotAllowed:
      description: Method Not Allowed
      headers:
        X-Correlator:
          $ref: '#/components/headers/X-Correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            MethodNotAllowed:
              description: |
                An HTTP verb other than GET has been used to try
                and access the resource.
              value:
                code: METHOD_NOT_ALLOWED
                status: 405
                message: The request method is not supported by this resource
    406Unacceptable:
      description: Not Acceptable
      headers:
        X-Correlator:
          $ref: '#/components/headers/X-Correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            NotAcceptable:
              description: A response format other than JSON has been requested
              value:
                code: NOT_ACCEPTABLE
                status: 406
                message: >-
                  The server cannot produce a response matching the content
                  requested by the client through Accept-* headers
    429TooManyRequests:
      description: Too Many Requests
      headers:
        X-Correlator:
          $ref: '#/components/headers/X-Correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            TooManyRequests:
              description: |
                Access to the API has been temporarily blocked due
                to quota or spike arrest limits being reached.
              value:
                code: TOO_MANY_REQUESTS
                status: 429
                message: Either out of resource quota or reaching rate limiting
    500InternalServerError:
      description: Internal Server Error
      headers:
        X-Correlator:
          $ref: '#/components/headers/X-Correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: INTERNAL
            status: 500
            message: The service is currently not available
    502BadGateway:
      description: Bad Gateway
      headers:
        X-Correlator:
          $ref: '#/components/headers/X-Correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: BAD_GATEWAY
            status: 502
            message: The service is currently not available
    503ServiceUnavailable:
      description: Service Unavailable
      headers:
        X-Correlator:
          $ref: '#/components/headers/X-Correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: UNAVAILABLE
            status: 503
            message: The service is currently not available
    504GatewayTimeout:
      description: Gateway Time-Out
      headers:
        X-Correlator:
          $ref: '#/components/headers/X-Correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: TIMEOUT
            status: 504
            message: The service is currently not available