openapi: 3.2.0 info: title: Simple Edge Discovery API version: 1.0.0 x-camara-commonalities: 0.4.0 description: "# Find the closest Edge Cloud Zone\n---\n# Summary\n\nThe Simple Edge Discovery API returns the name of the closest operator Edge\nCloud Zone to a particular user device.\n\n# Purpose\nNetwork operators may host multiple Edge Cloud Zones in a\ngiven territory. Connecting your application to a server on the closest\nEdge Cloud Zone means packets travel the shortest distance between\nendpoints, typically resulting in the lowest round-trip latency. Note, the\nphysical (GPS) location of a user device is not a reliable way to determine\nthe closest Edge Cloud Zone, due to the way operator networks are routed -\nso the operator will calculate the Edge Cloud Zone with the\n_shortest network path_to the network-attached device identified in the API\nrequest.\n\nOnce you have the name of the closest Edge Cloud Zone to the user device,\nyou may:\n\n* connect the application client on the user device to your application\nserver instance on that Edge Cloud Zone. Note: the address of that server\ninstance is not part of the API response, but should be known in advance.\n* or, if you have no instance on that Edge Cloud Zone, you may wish to\ndeploy one there.\n\nNote: the provider of the Edge Cloud Zone may be an operator, or a cloud\nprovider working in partnership with the operator.\n\n# Usage\n\nThe API may be called either by an application client hosted on a device\nattached to the operator network (i.e. phone, tablet), or by a server.\n\nThere is a single API endpoint: `/edge-cloud-zones?filter=closest`. To call\nthis endpoint, the API consumer must first obtain a valid OAuth2 token from\nthe token endpoint, and pass it as an `Authorization` header in the API\nrequest.\n\n# Identifying the device\n\nThe API returns the closest Edge Cloud Zone to a given device, so that\ndevice needs to be identifiable by the network. This can be achieved either\nby passing a device identifier in the request header, or, from the 3-legged\naccess token where implemented by the operator.\n\n## Passing a device identifier in the request header\n\n* If you call the API from a server, you must explicitly pass one or\nmore device identifiers in the HTTP request header:\n * `IPv4-Address` or `IPv6-Address`. This is the public IP address of the\n user device: this\n can be obtained by an application hosted on that device calling a\n public IP address API (e.g. GET https://api.ipify.org?format=json)\n * If you provide an `IPv4-Address` or `IPv6-Address`: for certain\n operators you may be required to also provide a `Public-port` header.\n * `Phone-Number` . The international E.164 format (starting with country\n code), e.g. +4407123123456\n * `Network-Access-Identifier` (where available from the API host operator)\n\n* If you call the API from a device attached to the operator network, then\nyou can attempt the request without passing device identifier(s) parameters\nin the request header. If that returns a 422 `UNIDENTIFIABLE_DEVICE`\nerror then retry the request but this time include a device identifier.\n\nNOTE1: the network operator might support only a subset of these options.\nThe API invoker can provide multiple identifiers to be compatible across\ndifferent network operators. In this case the identifiers MUST belong to the\nsame device.\n\nNOTE2: for the Commonalities release v0.4, we are enforcing that the\n`networkAccessIdentifier` is only part of the schema for future-proofing, and\nCAMARA does not currently allow its use. After the CAMARA meta-release work\nis concluded and the relevant issues are resolved, its use will need to be\nexplicitly documented in the guidelines.\n\n### Example requests:\n\nExamples for all API clients:\n```\n GET /edge-cloud-zones?filter=closest HTTP/1.1\n Host: example.com\n Accept: application/json\n IPv4-Address: 84.125.93.10\n\n GET /edge-cloud-zones?filter=closest HTTP/1.1\n Host: example.com\n Accept: application/json\n Phone-Number: +441234567890\n```\nExample where the network operator requires the public port to be passed:\n```\n GET /edge-cloud-zones?filter=closest HTTP/1.1\n Host: example.com\n Accept: application/json\n IPv4-Address: 84.125.93.10\n Public-port: 1234\n```\n\nExample where API client is on a network-attached device:\n```\n GET /edge-cloud-zones?filter=closest HTTP/1.1\n Host: example.com\n Accept: application/json\n```\n\n## Identifying a device from the access token\n\nThis specification defines the `device` identifying headers as optional in\nAPI requests, specifically in cases where the API is accessed using a\n3-legged access token and the device can be uniquely identified by the token.\nThis approach simplifies API usage for API consumers by relying on the device\ninformation associated with the access token used to invoke the API.\n\n### Handling of device information:\n\n#### Optional device identifying headers for 3-legged tokens:\n\n- When using a 3-legged access token, the device associated with the access\n token must be considered as the device for the API request. This means that\n a device identifying header is not required in the request, and if\n included it must identify the same device, therefore **it is recommended\n NOT to include it in these scenarios** to simplify the API usage and avoid\n additional validations.\n\n#### Validation mechanism:\n\n- The server will extract the device identification from the access token, if\n available.\n- If the API request additionally includes a `device` identifying header\n when using a 3-legged access token, the API will validate that the device\n identifier provided matches the one associated with the access token.\n- If there is a mismatch, the API will respond with a\n 403 `INVALID_TOKEN_CONTEXT` error, indicating that the device information\n in the request does not match the token.\n\n#### Error handling for unidentifiable devices:\n\n- If the `device` identifying header is not included in the request and the\n device information cannot be derived from the 3-legged access token, nor\n inferred by the operator if the request is made directly from the client,\n the server will return a 422 `UNIDENTIFIABLE_DEVICE` error.\n\n#### Restrictions for tokens without an associated authenticated identifier:\n\n- For scenarios which do not have a single device identifier associated to\n the token during the authentication flow, e.g. 2-legged access tokens, a\n `device` identifying header MUST be provided in the API request. This\n ensures that the device identification is explicit and valid for each API\n call made with these tokens.\n\n# Responses\n\n## Success\n\nA JSON object is returned containing an array with a single member object.\nThis contains identifiers for the closest Edge Cloud Zone. The HTTP status\ncode will be`200 OK`. An example response:\n\n```\n[\n {\n \"edgeCloudZoneId\": \"4gt555-6457-7890-d4he-1dc79f44gb66\",\n \"edgeCloudZoneName\": \"example zone name\",\n \"edgeCloudProvider\": \"example zone provider\"\n }\n]\n```\n* `edgeCloudZoneId` is a UUID for the Edge Cloud Zone.\n* `edgeCloudZoneName` is the common name of the closest Edge Cloud Zone to\nthe user device.\n* `edgeCloudProvider` is the name of the operator or cloud provider of\nthe Edge Cloud Zone.\n\n## Errors\n\nIf the authentication token is not valid, a `401 UNAUTHENTICATED` error is\nreturned.\n\nIf the mobile subscription parameters contain a formatting error, a `400\nINVALID_ARGUMENT` error is returned.\n\nIf the mobile subscription cannot be identified from the provided\nparameters, a `404 NOT_FOUND` error is returned.\n\nAny more general service failures will result in an error in the `5xx`range\nwith an explanation.\n\n# Notes for Simple Edge Discovery API publishers\n\nIf an `IPv4-Address` or `IPv6-Address` header parameter is provided then the\noperator should\nassume the request is coming from a developer's server rather than a device\nattached to the network. In which case the developer server is expected to\nhave been provided with the device public IP address (e.g. by the\napplication client on that device signalling it back to the server).\n\nIf neither an `IPv4-Address`/`IPv6-Address` parameter, nor any other device\nidentifier, is\nprovided in the API request header then the operator should assume the\nrequest is from a device attached to their network, and attempt to use the\npublic IP source address to determine which packet gateway issued it (and\nhence the closest edge to that gateway).\n\nIf no `IPv4-Address`/`IPv6-Address` header parameter is provided, but another\ndevice\nidentifier(s) is provided, then the operator should assume the request is\ncoming from a device attached to their network and should make use of one\nor both of the public IP source address (from the IP packet header) and the\ndevice identifier(s) provided in the HTTPS request header.\n\nShould your implementation require the `Port` value to be passed in addition\nto the `IP-Address`, please make that explicit in the documentation, and\nutilise the `GENERIC_400_MISSING_PORT` error if the `Port` header is omitted.\n\n# Authorization and authentication\n\nThe \"Camara Security and Interoperability Profile\" provides details on how a\nclient requests an access token. Please refer to Identify and Consent\nManagement (https://github.com/camaraproject/IdentityAndConsentManagement/)\nfor the released version of the Profile.\n\nWhich specific authorization flows are to be used will be determined during\nonboarding process, happening between the API Client and the Telco Operator\nexposing the API, taking into account the declared purpose for accessing\nthe API, while also being subject to the prevailing legal framework\ndictated by local legislation.\n\nIt is important to remark that in cases where personal user data is\nprocessed by the API, and users can exercise their rights through\nmechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens\nbecomes mandatory. This measure ensures that the API remains in strict\ncompliance with user privacy preferences and regulatory obligations,\nupholding the principles of transparency and user-centric data control.\n\n# Further info and support\n\n---\n" license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html 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\nrequest, the API provider must include it in the response with\nthe same value that was used in the request. Otherwise, it is\noptional to include the \"x-correlator\" header in the response with\n any valid value. Recommendation is to use UUID for values.\n" 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: schemas: 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 SingleIpv4Addr: description: A single IPv4 address with no subnet mask type: string format: ipv4 example: 84.125.93.10 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' 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 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' 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 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 Port: description: TCP or UDP port number type: integer minimum: 0 maximum: 65535 EdgeCloudProvider: description: 'The company name of the Edge Cloud Zone provider. ' type: string 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 responses: 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' 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' 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' 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' 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' 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' 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' 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' 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' 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' headers: x-correlator: description: "When the API Consumer includes the \"x-correlator\" header in the request,\n the API provider must include it in the response with the same value t\n hat was used in the request. Otherwise, it is optional to include the\n \"x-correlator\" header in the response with any valid value.\n Recommendation is to use UUID for values.\n" required: false schema: type: string securitySchemes: openId: description: OpenID Provider Configuration Information. type: openIdConnect openIdConnectUrl: .well-known/openid-configuration externalDocs: description: Product documentation at CAMARA. url: https://github.com/camaraproject/EdgeCloud