diff --git a/code/API_definitions/Discovery/simple_edge_discovery.yaml b/code/API_definitions/Discovery/simple_edge_discovery.yaml index 8e132ca0..51f6883f 100644 --- a/code/API_definitions/Discovery/simple_edge_discovery.yaml +++ b/code/API_definitions/Discovery/simple_edge_discovery.yaml @@ -2,7 +2,7 @@ openapi: 3.0.3 info: title: Simple Edge Discovery API - version: 0.9.4 + version: 0.9.4-rc.1 description: | # Find the closest Edge Cloud Zone --- @@ -12,13 +12,13 @@ info: Cloud Zone to a particular user device. # Purpose - Network operators may host multiple Multi-access Edge Cloud Zones in a + 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 + so the operator will calculate the Edge Cloud Zone with the _shortest network path_to the network-attached device identified in the API request. @@ -77,7 +77,7 @@ info: GET /edge-cloud-zones?filter=closest HTTP/1.1 Host: example.com Accept: application/json - Phone-Number: 441234567890 + Phone-Number: +441234567890 ``` Example where API client is on a network-attached device: @@ -92,7 +92,7 @@ info: ## Success - A JSON object is returned containing an array with a single member object. + 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: @@ -100,8 +100,8 @@ info: [ { "edgeCloudZoneId": "4gt555-6457-7890-d4he-1dc79f44gb66", - "edgeCloudZoneName": "eu-west-2-wl1-man-wlz-1", - "edgeCloudProvider": "AWS" + "edgeCloudZoneName": "example zone name", + "edgeCloudProvider": "example zone provider" } ] ``` @@ -125,7 +125,7 @@ info: Any more general service failures will result in an error in the `5xx`range with an explanation. - # Notes for Simple Edge API publishers + # Notes for Simple Edge Discovery API publishers If an `IP-Address` header parameter is provided then the operator should assume the request is coming from a developer's server rather than a device @@ -148,7 +148,7 @@ info: # Authorization and authentication CAMARA guidelines defines a set of authorization flows which can grant API - clients access to the API functionality, as outlined in the document + clients access to the API functionality, as outlined in the document [CAMARA-API-access-and-user-consent.md] (https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md). Which specific authorization flows are to be used will be determined during @@ -202,53 +202,50 @@ paths: - name: filter in: query required: true - description: | + description: | Filter the Edge Cloud Zones according to the parameter value. For this API the only supported value is `closest`. schema: type: string - enum: + enum: - closest - - name: IP-Address + - name: IPv4-Address in: header required: false - description: The public IP allocated to the device. - examples: - ipv4: - value: "84.125.93.10" - ipv6: - value: "2001:db8:85a3:8d3:1319:8a2e:370:7344" + description: The public IPv4 address allocated to the device. + example: "84.125.93.10" schema: - type: string - format: ipv4/ipv6 - oneOf: - - pattern: '^(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5] - )\.){3}([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])$' - - 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})))$' + $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: | + description: | 3GPP network access identifier for the subscription being used by the device. example: "4d596ac1-7822-4927-a3c5-d72e1f922c94@domain.com" required: false schema: - type: string - format: email + $ref: "#/components/schemas/NetworkAccessIdentifier" + - name: Phone-Number in: header - example: "441234567890" + 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: - type: string - pattern: '^\+?[0-9]{5,15}$' + $ref: "#/components/schemas/PhoneNumber" responses: "200": @@ -318,20 +315,12 @@ components: Provider object (the name of the cloud provider or operator hosting that edge cloud zone). properties: - edgeCloudZone: - 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 egde cloud zone). - type: object - properties: - edgeCloudZoneId: - $ref: "#/components/schemas/EdgeCloudZoneId" - edgeCloudZoneName: - $ref: "#/components/schemas/EdgeCloudZoneName" - edgeCloudProvider: - $ref: "#/components/schemas/EdgeCloudProvider" + edgeCloudZoneId: + $ref: "#/components/schemas/EdgeCloudZoneId" + edgeCloudZoneName: + $ref: "#/components/schemas/EdgeCloudZoneName" + edgeCloudProvider: + $ref: "#/components/schemas/EdgeCloudProvider" EdgeCloudZoneId: description: | @@ -340,7 +329,6 @@ components: format: uuid additionalProperties: false - EdgeCloudZoneName: description: | Edge Cloud Zone Name - the common name for the Edge Cloud Zone. @@ -352,8 +340,6 @@ components: The company name of the Edge Cloud Zone provider. type: string - - ErrorResponse: description: Error code and human-readable description. type: object @@ -370,6 +356,30 @@ components: This parameter appears when there is an error. A human readable explanation specific to this occurrence of the problem. + + 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 ################################### @@ -578,3 +588,5 @@ components: "status": 504, "message": "The service is currently not available" } + +