GSMA Open Gateway Simple Edge Discovery API

---
openapi: 3.0.3
info:
 title: Simple Edge Discovery
 version: 1.0.0
 x-camara-commonalities: 0.4.0
 description: |
  # Find the closest Edge Cloud Zone
  ---
  # Summary

  The Simple Edge Discovery API returns the name of the closest operator Edge
  Cloud Zone to a particular user device.

  # Purpose
  Network operators may host multiple Edge Cloud Zones in a
  given territory. Connecting your application to a server on the closest
  Edge Cloud Zone means packets travel the shortest distance between
  endpoints, typically resulting in the lowest round-trip latency. Note, the
  physical (GPS) location of a user device is not a reliable way to determine
  the closest Edge Cloud Zone, due to the way operator networks are routed -
  so the operator will calculate the Edge Cloud Zone with the
  _shortest network path_to the network-attached device identified in the API
  request.

  Once you have the name of the closest Edge Cloud Zone to the user device,
  you may:

  * connect the application client on the user device to your application
  server instance on that Edge Cloud Zone. Note: the address of that server
  instance is not part of the API response, but should be known in advance.
  * or, if you have no instance on that Edge Cloud Zone, you may wish to
  deploy one there.

  Note: the provider of the Edge Cloud Zone may be an operator, or a cloud
  provider working in partnership with the operator.

  # Usage

  The API may be called either by an application client hosted on a device
  attached to the operator network (i.e. phone, tablet), or by a server.

  There is a single API endpoint: `/edge-cloud-zones?filter=closest`. To call
  this endpoint, the API consumer must first obtain a valid OAuth2 token from
  the token endpoint, and pass it as an `Authorization` header in the API
  request.

  # Identifying the device

  The API returns the closest Edge Cloud Zone to a given device, so that
  device needs to be identifiable by the network. This can be achieved either
  by passing a device identifier in the request header, or, from the 3-legged
  access token where implemented by the operator.

  ## Passing a device identifier in the request header

  * If you call the API from a server, you must explicitly pass one or
  more device identifiers in the HTTP request header:
    * `IPv4-Address` or `IPv6-Address`. This is the public IP address of the
    user device: this
    can be obtained by an application hosted on that device calling a
    public IP address API (e.g. GET https://api.ipify.org?format=json)
    * If you provide an `IPv4-Address` or `IPv6-Address`: for certain
    operators you may be required to also provide a `Public-port` header.
    * `Phone-Number` . The international E.164 format (starting with country
    code), e.g. +4407123123456
    * `Network-Access-Identifier` (where available from the API host operator)

  * If you call the API from a device attached to the operator network, then
  you can attempt the request without passing device identifier(s) parameters
  in the request header. If that returns a 422 `UNIDENTIFIABLE_DEVICE`
  error then retry the request but this time include a device identifier.

  NOTE1: the network operator might support only a subset of these options.
  The API invoker can provide multiple identifiers to be compatible across
  different network operators. In this case the identifiers MUST belong to the
  same device.

  NOTE2: for the Commonalities release v0.4, we are enforcing that the
  `networkAccessIdentifier` is only part of the schema for future-proofing, and
  CAMARA does not currently allow its use. After the CAMARA meta-release work
  is concluded and the relevant issues are resolved, its use will need to be
  explicitly documented in the guidelines.

  ### Example requests:

  Examples for all API clients:
  ```
    GET /edge-cloud-zones?filter=closest HTTP/1.1
    Host: example.com
    Accept: application/json
    IPv4-Address: 84.125.93.10

    GET /edge-cloud-zones?filter=closest HTTP/1.1
    Host: example.com
    Accept: application/json
    Phone-Number: +441234567890
  ```
  Example where the network operator requires the public port to be passed:
  ```
    GET /edge-cloud-zones?filter=closest HTTP/1.1
    Host: example.com
    Accept: application/json
    IPv4-Address: 84.125.93.10
    Public-port: 1234
  ```

  Example where API client is on a network-attached device:
  ```
    GET /edge-cloud-zones?filter=closest HTTP/1.1
    Host: example.com
    Accept: application/json
  ```

  ## Identifying a device from the access token

  This specification defines the `device` identifying headers as optional in
  API requests, specifically in cases where the API is accessed using a
  3-legged access token and the device can be uniquely identified by the token.
  This approach simplifies API usage for API consumers by relying on the device
  information associated with the access token used to invoke the API.

  ### Handling of device information:

  #### Optional device identifying headers for 3-legged tokens:

  - When using a 3-legged access token, the device associated with the access
    token must be considered as the device for the API request. This means that
    a device  identifying header  is not required in the request, and if
    included it must identify the same device, therefore **it is recommended
    NOT to include it in these scenarios** to simplify the API usage and avoid
    additional validations.

  #### Validation mechanism:

  - The server will extract the device identification from the access token, if
    available.
  - If the API request additionally includes a `device`  identifying header
    when using a 3-legged access token, the API will validate that the device
    identifier provided matches the one associated with the access token.
  - If there is a mismatch, the API will respond with a
    403 `INVALID_TOKEN_CONTEXT` error, indicating that the device information
    in the request does not match the token.

  #### Error handling for unidentifiable devices:

  - If the `device`  identifying header is not included in the request and the
    device information cannot be derived from the 3-legged access token, nor
    inferred by the operator if the request is made directly from the client,
    the server will return a 422 `UNIDENTIFIABLE_DEVICE` error.

  #### Restrictions for tokens without an associated authenticated identifier:

  - For scenarios which do not have a single device identifier associated to
    the token during the authentication flow, e.g. 2-legged access tokens, a
    `device` identifying header MUST be provided in the API request. This
    ensures that the device identification is explicit and valid for each API
    call made with these tokens.

  # Responses

  ## Success

  A JSON object is returned containing an array with a single member object.
  This contains identifiers for the closest Edge Cloud Zone. The HTTP status
  code will be`200 OK`. An example response:

  ```
  [
    {
      "edgeCloudZoneId": "4gt555-6457-7890-d4he-1dc79f44gb66",
      "edgeCloudZoneName": "example zone name",
      "edgeCloudProvider": "example zone provider"
    }
  ]
  ```
  * `edgeCloudZoneId` is a UUID for the Edge Cloud Zone.
  * `edgeCloudZoneName` is the common name of the closest Edge Cloud Zone to
  the user device.
  * `edgeCloudProvider` is the name of the operator or cloud provider of
  the Edge Cloud Zone.

  ## Errors

  If the authentication token is not valid, a `401 UNAUTHENTICATED` error is
  returned.

  If the mobile subscription parameters contain a formatting error, a `400
  INVALID_ARGUMENT` error is returned.

  If the mobile subscription cannot be identified from the provided
  parameters, a `404 NOT_FOUND` error is returned.

  Any more general service failures will result in an error in the `5xx`range
  with an explanation.

  # Notes for Simple Edge Discovery API publishers

  If an `IPv4-Address` or `IPv6-Address` header parameter is provided then the
  operator should
  assume the request is coming from a developer's server rather than a device
  attached to the network. In which case the developer server is expected to
  have been provided with the device public IP address (e.g. by the
  application client on that device signalling it back to the server).

  If neither an `IPv4-Address`/`IPv6-Address` parameter, nor any other device
  identifier,  is
  provided in the API request header then the operator should assume the
  request is from a device attached to their network, and attempt to use the
  public IP source address to determine which packet gateway issued it (and
  hence the closest edge to that gateway).

  If no `IPv4-Address`/`IPv6-Address` header parameter is provided, but another
  device
  identifier(s) is provided, then the operator should assume the request is
  coming from a device attached to their network and should make use of one
  or both of the public IP source address (from the IP packet header) and the
  device identifier(s) provided in the HTTPS request header.

  Should your implementation require the `Port` value to be passed in addition
  to the `IP-Address`, please make that explicit in the documentation, and
  utilise the `GENERIC_400_MISSING_PORT` error if the `Port` header is omitted.

  # Authorization and authentication

  The "Camara Security and Interoperability Profile" provides details on how a
  client requests an access token. Please refer to Identify and Consent
  Management (https://github.com/camaraproject/IdentityAndConsentManagement/)
  for the released version of the Profile.

  Which specific authorization flows are to be used will be determined during
  onboarding process, happening between the API Client and the Telco Operator
  exposing the API, taking into account the declared purpose for accessing
  the API, while also being subject to the prevailing legal framework
  dictated by local legislation.

  It is important to remark that in cases where personal user data is
  processed by the API, and users can exercise their rights through
  mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens
  becomes mandatory. This measure ensures that the API remains in strict
  compliance with user privacy preferences and regulatory obligations,
  upholding the principles of transparency and user-centric data control.

  # Further info and support

  ---

 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}/simple-edge-discovery/v1"
   variables:
    apiRoot:
     default: https://localhost:9091
     description: |
      API root, defined by the service provider, e.g.
      `api.example.com` or `api.example.com/somepath`

tags:
 - name: Discovery
   description: |
    Find the closest Edge Cloud Zone to the user device.

paths:
 /edge-cloud-zones:
  get:
   security:
    - openId:
       - simple-edge-discovery:edge-cloud-zones:read
   operationId: readClosestEdgeCloudZone
   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 by the network operator.
      example: "84.125.93.10"
      schema:
       $ref: "#/components/schemas/SingleIpv4Addr"

    - name: Public-port
      in: header
      required: false
      description: The public TCP or UDP port allocated to the device by the network operator.
      example: 123
      schema:
       $ref: "#/components/schemas/Port"

    - name: IPv6-Address
      in: header
      required: false
      description: The public IPv6 address allocated to the device by the network operator.
      example: "2001:db8:85a3:8d3:1319:8a2e:370:7348"
      schema:
       $ref: "#/components/schemas/DeviceIpv6Address"

    - name: Network-Access-Identifier
      in: header
      required: false
      description: |
       3GPP network access identifier for the subscription
       being used by the device.
      schema:
       $ref: "#/components/schemas/NetworkAccessIdentifier"

    - name: Phone-Number
      in: header
      example: "+441234567890"
      required: false
      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: 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

   responses:
    "200":
     description: |
      Successful response, returning the closest Edge Cloud
      Zone to the user device identified in the request header.
     headers:
      x-correlator:
       $ref: "#/components/headers/x-correlator"
     content:
      application/json:
       schema:
        $ref: "#/components/schemas/EdgeCloudZones"
    "400":
     description: |
      Client eror - the required querystring was not provided
     headers:
      x-correlator:
       $ref: "#/components/headers/x-correlator"
     content:
      application/json:
       schema:
        $ref: "#/components/schemas/ErrorInfo"
       examples:
        InvalidQuerystring:
         summary: Invalid querystring
         description: The 'filter' querystring parameter is
          missing or does not have a value of 'closest'
         value:
          status: 400
          code: INVALID_QUERYSTRING
          message: "Querystring must be provided: filter=closest"
    "401":
     $ref: "#/components/responses/Generic401"
    "403":
     $ref: "#/components/responses/Generic403"
    "404":
     $ref: "#/components/responses/Generic404"
    "406":
     $ref: "#/components/responses/Generic406"
    "422":
     $ref: "#/components/responses/Generic422"
    "429":
     $ref: "#/components/responses/Generic429"
    "500":
     $ref: "#/components/responses/Generic500"
    "501":
     $ref: "#/components/responses/Generic501"
    "502":
     $ref: "#/components/responses/Generic502"
    "503":
     $ref: "#/components/responses/Generic503"
    "504":
     $ref: "#/components/responses/Generic504"

   tags:
    - Discovery
   summary: |
    Returns the name of the Edge Cloud Zone closest to user device
    identified in the request.
   description: |
    On receiving this request, the network will return the name
    of the Edge Cloud Zone 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

 schemas:
  EdgeCloudZones:
   type: array
   items:
    $ref: "#/components/schemas/EdgeCloudZone"
   minItems: 1
   description: |
    A collection of Edge Cloud Zones. For this Simple Edge
    Discovery API the collection will have at most one member (the closest
    Edge Cloud Zone to the user device indicated in the request).
   additionalProperties: false

  EdgeCloudZone:
   type: object
   description: |
    An Edge Cloud Zone, uniquely identified by a combination
    of the value of the Edge Resource Name object and the value of the
    Provider object (the name of the cloud provider or operator hosting that
    edge cloud zone).
   properties:
    edgeCloudZoneId:
     $ref: "#/components/schemas/EdgeCloudZoneId"
    edgeCloudZoneName:
     $ref: "#/components/schemas/EdgeCloudZoneName"
    edgeCloudProvider:
     $ref: "#/components/schemas/EdgeCloudProvider"

  EdgeCloudZoneId:
   description: |
    Operator-issued UUID for the Edge Cloud Zone.
   type: string
   format: uuid
   additionalProperties: false

  EdgeCloudZoneName:
   description: |
    Edge Cloud Zone Name - the common name for the Edge Cloud Zone.
   type: string
   additionalProperties: false

  EdgeCloudProvider:
   description: |
    The company name of the Edge Cloud Zone provider.
   type: string

  ErrorInfo:
   type: object
   description: Error information
   required:
    - message
    - status
    - code
   properties:
    message:
     type: string
     description: A human readable description of what the event represents
    status:
     type: integer
     description: HTTP response status code
    code:
     type: string
     description: Friendly Code to describe the error

  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"

  Port:
   description: TCP or UDP port number
   type: integer
   minimum: 0
   maximum: 65535

 responses:
  Generic401:
   description: Unauthorized
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     examples:
      GENERIC_401_UNAUTHENTICATED:
       description: Request cannot be authenticated
       value:
        status: 401
        code: UNAUTHENTICATED
        message: Request not authenticated due to missing, invalid, or expired credentials.
      GENERIC_401_AUTHENTICATION_REQUIRED:
       description: New authentication is needed, authentication is no longer valid
       value:
        status: 401
        code: AUTHENTICATION_REQUIRED
        message: New authentication is required.
   headers:
    x-correlator:
     $ref: "#/components/headers/x-correlator"
  Generic403:
   description: Forbidden
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     examples:
      GENERIC_403_PERMISSION_DENIED:
       description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
       value:
        status: 403
        code: PERMISSION_DENIED
        message: Client does not have sufficient permissions to perform this action.
      GENERIC_403_INVALID_TOKEN_CONTEXT::
       description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token
       value:
        status: 403
        code: INVALID_TOKEN_CONTEXT
        message: "{{field}} is not consistent with access token."
   headers:
    x-correlator:
     $ref: "#/components/headers/x-correlator"
  Generic404:
   description: Not found
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     examples:
      GENERIC_404_NOT_FOUND:
       description: Resource is not found
       value:
        status: 404
        code: NOT_FOUND
        message: The specified resource is not found.
      GENERIC_404_DEVICE_NOT_FOUND:
       description: Device identifier not found
       value:
        status: 404
        code: DEVICE_NOT_FOUND
        message: Device identifier not found.
   headers:
    x-correlator:
     $ref: "#/components/headers/x-correlator"
  Generic406:
   description: Not Acceptable
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     examples:
      GENERIC_406_NOT_ACCEPTABLE:
       description: |
        API Server does not accept the media type (`Accept-*` header) indicated by API client
       value:
        status: 406
        code: NOT_ACCEPTABLE
        message: |
         The server cannot produce a response matching the content requested by the client
         through `Accept-*` headers.
   headers:
    x-correlator:
     $ref: "#/components/headers/x-correlator"
  Generic422:
   description: Unprocessable Content
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     examples:
      GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH:
       description: Inconsistency between device identifiers not pointing to the same device
       value:
        status: 422
        code: DEVICE_IDENTIFIERS_MISMATCH
        message: Provided device identifiers are not consistent.
      GENERIC_422_DEVICE_NOT_APPLICABLE:
       description: Service is not available for the provided device
       value:
        status: 422
        code: DEVICE_NOT_APPLICABLE
        message: The Service is not available for the provided device.
      GENERIC_422_UNIDENTIFIABLE_DEVICE:
       description: The device identifier is not included in the request and the device information cannot be derived from the 3-legged access token
       value:
        status: 422
        code: UNIDENTIFIABLE_DEVICE
        message: The device cannot be identified.
   headers:
    x-correlator:
     $ref: "#/components/headers/x-correlator"
  Generic429:
   description: Too Many Requests
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     examples:
      GENERIC_429_QUOTA_EXCEEDED:
       description: Request is rejected due to exceeding a business quota limit
       value:
        status: 429
        code: QUOTA_EXCEEDED
        message: Either out of resource quota or reaching rate limiting.
      GENERIC_429_TOO_MANY_REQUESTS:
       description: API Server request limit is overpassed
       value:
        status: 429
        code: TOO_MANY_REQUESTS
        message: Either out of resource quota or reaching rate limiting.
   headers:
    x-correlator:
     $ref: "#/components/headers/x-correlator"
  Generic500:
   description: Internal Server Error
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     examples:
      GENERIC_500_INTERNAL:
       description: Problem in Server side. Regular Server Exception
       value:
        status: 500
        code: INTERNAL
        message: Unknown server error. Typically a server bug.
   headers:
    x-correlator:
     $ref: "#/components/headers/x-correlator"
  Generic501:
   description: Not Implemented
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     examples:
      GENERIC_501_NOT_IMPLEMENTED:
       description: Service not implemented. The use of this code should be avoided as far as possible to get the objective to reach aligned implementations
       value:
        status: 501
        code: NOT_IMPLEMENTED
        message: This functionality is not implemented yet.
   headers:
    x-correlator:
     $ref: "#/components/headers/x-correlator"
  Generic502:
   description: Bad Gateway
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     examples:
      GENERIC_502_BAD_GATEWAY:
       description: Internal routing problem in the Server side that blocks to manage the service properly
       value:
        status: 502
        code: BAD_GATEWAY
        message: An upstream internal service cannot be reached.
   headers:
    x-correlator:
     $ref: "#/components/headers/x-correlator"
  Generic503:
   description: Service Unavailable
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     examples:
      GENERIC_503_UNAVAILABLE:
       description: Service is not available. Temporary situation usually related to maintenance process in the server side
       value:
        status: 503
        code: UNAVAILABLE
        message: Service Unavailable.
   headers:
    x-correlator:
     $ref: "#/components/headers/x-correlator"
  Generic504:
   description: Gateway Timeout
   content:
    application/json:
     schema:
      $ref: "#/components/schemas/ErrorInfo"
     examples:
      GENERIC_504_TIMEOUT:
       description: API Server Timeout
       value:
        status: 504
        code: TIMEOUT
        message: Request timeout exceeded.
   headers:
    x-correlator:
     $ref: "#/components/headers/x-correlator"