You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: code/API_definitions/Discovery/simple_edge_discovery.yaml
+136-65
Original file line number
Diff line number
Diff line change
@@ -1,3 +1,4 @@
1
+
---
1
2
openapi: 3.0.3
2
3
info:
3
4
title: Simple Edge Discovery API
@@ -7,62 +8,92 @@ info:
7
8
---
8
9
# Summary
9
10
10
-
The Simple Edge Discovery API returns the name of the closest operator MEC platform to a particular user device.
11
+
The Simple Edge Discovery API returns the name of the closest operator MEC
12
+
platform to a particular user device.
11
13
12
14
# Purpose
13
-
Network operators may host multiple Multi-access Edge Computing (MEC, or 'Edge') platforms in a given territory. Connecting your application to a server on the closest MEC platform 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 MEC platform, due to the way operator networks are routed - so the operator will calculate the MEC platform with the _shortest network path_ to the network-attached device identified in the API request.
14
-
15
-
Once you have the name of the closest MEC platform to the user device, you may:
16
-
17
-
* connect the application client on the user device to your application server instance on that MEC platform. Note: the address of that server instance is not part of the API response, but should be known in advance.
18
-
* or, if you have no instance on that MEC platform, you may wish to deploy one there.
19
-
20
-
# Usage
21
-
22
-
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.
23
-
24
-
There is a single API endpoint: `/mecplatforms?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.
25
-
26
-
The API returns the closest MEC platform to a given device, so that device needs to be identifiable by the network:
27
-
* if you call the API from a server, you must explicitly pass one or more device identifiers in the HTTP request header:
28
-
* `IP-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)
29
-
* `Phone-Number` . The international E.164 format (starting with country code), e.g. +4407123123456
15
+
Network operators may host multiple Multi-access Edge Computing (MEC, or
16
+
'Edge') platforms in a given territory. Connecting your application to a
17
+
server on the closest MEC platform means packets travel the shortest
18
+
distance between endpoints, typically resulting in the lowest round-trip
19
+
latency. Note, the physical (GPS) location of a user device is not a
20
+
reliable way to determine the closest MEC platform, due to the way operator
21
+
networks are routed - so the operator will calculate the MEC platform with
22
+
the _shortest network path_ to the network-attached device identified in
23
+
the API request.
24
+
25
+
Once you have the name of the closest MEC platform to the user device, you
26
+
may:
27
+
28
+
* connect the application client on the user device to your application
29
+
server instance on that MEC platform. Note: the address of that server
30
+
instance is not part of the API response, but should be known in advance.
31
+
* or, if you have no instance on that MEC platform, you may wish to deploy
32
+
one there.
33
+
34
+
# Usage
35
+
36
+
The API may be called either by an application client hosted on a device
37
+
attached to the operator network (i.e. phone, tablet), or by a server.
38
+
39
+
There is a single API endpoint: `/mecplatforms?filter=closest`. To call
40
+
this endpoint, the API consumer must first obtain a valid OAuth2 token from
41
+
the token endpoint, and pass it as an `Authorization` header in the API
42
+
request.
43
+
44
+
The API returns the closest MEC platform to a given device, so that device
45
+
needs to be identifiable by the network:
46
+
47
+
* If you call the API from a server, you must explicitly pass one or
48
+
more device identifiers in the HTTP request header:
49
+
* `IP-Address`. This is the public IP address of the user device: this can
50
+
be obtained by an application hosted on that device calling a public IP
51
+
address API (e.g. GET https://api.ipify.org?format=json)
52
+
* `Phone-Number` . The international E.164 format (starting with country
53
+
code), e.g. +4407123123456
30
54
* `Network-Access-Identifier` (where available from the API host operator)
31
55
32
-
* if you call the API from a device attached to the operator network, you _may_ omit the explicit device identifier(s)from the request header. If such a request fails with a `404 Not Found` error then retry the request but this time include a device identifier.
56
+
* If you call the API from a device attached to the operator network, you
57
+
_may_ omit the explicit device identifier(s)from the request header. If such
58
+
a request fails with a `404 Not Found` error then retry the request but this
59
+
time include a device identifier.
33
60
34
-
The provider of the MEC Platform may be an operator, or a cloud provider. The
61
+
The provider of the MEC Platform may be an operator, or a cloud provider.
Example where API client is on a network-attached device:
56
83
57
-
GET /mec-platforms?filter=closest HTTP/1.1
58
-
Host: example.com
59
-
Accept: application/json
84
+
GET /mec-platforms?filter=closest HTTP/1.1
85
+
Host: example.com
86
+
Accept: application/json
60
87
61
88
# Responses
62
89
63
90
## Success
64
91
65
-
A JSON object is returned containing a `MECPlatforms` array with a single member, along with the HTTP `200 OK` status code. The value of the `edgeCloudProvider` object is the name of the operator or cloud provider of the MEC Platform. `edgeResourceName` object is the name of the closest MEC platform to the user device. An example of this JSON object is as follows:
92
+
A JSON object is returned containing a `MECPlatforms` array with a single
93
+
member, along with the HTTP `200 OK` status code. The value of the
94
+
`edgeCloudProvider` object is the name of the operator or cloud provider of
95
+
the MEC Platform. `edgeResourceName` object is the name of the closest MEC
96
+
platform to the user device. An example of this JSON object is as follows:
66
97
```
67
98
{
68
99
"MecPlatforms": [
@@ -75,16 +106,22 @@ info:
75
106
```
76
107
## Errors
77
108
78
-
If the authentication token is not valid, a `401 UNAUTHENTICATED` error is returned.
109
+
If the authentication token is not valid, a `401 UNAUTHENTICATED` error is
110
+
returned.
79
111
80
-
If the mobile subscription parameters contain a formatting error, a `400 INVALID_ARGUMENT` error is returned.
112
+
If the mobile subscription parameters contain a formatting error, a `400
113
+
INVALID_ARGUMENT` error is returned.
81
114
82
-
If the mobile subscription cannot be identified from the provided parameters, a `404 NOT_FOUND` error is returned.
115
+
If the mobile subscription cannot be identified from the provided
116
+
parameters, a `404 NOT_FOUND` error is returned.
83
117
84
-
Any more general service failures will result in an error in the `5xx`range with an explanation.
118
+
Any more general service failures will result in an error in the `5xx`range
119
+
with an explanation.
85
120
86
121
# Note for Simple Edge API publishers
87
-
The API publisher (i.e. the operator implementation) must ensure that the tuple of edgeCloudProvider+edgeResourceName in the success response is unique.
122
+
The API publisher (i.e. the operator implementation) must ensure that the
123
+
tuple of edgeCloudProvider+edgeResourceName in the success response is
124
+
unique.
88
125
89
126
# Further info and support
90
127
@@ -123,7 +160,8 @@ paths:
123
160
- name: filter
124
161
in: query
125
162
required: true
126
-
description: Filter the MEC Platforms according to the parameter value. For this API the only supported value is `closest`.
163
+
description: Filter the MEC Platforms according to the parameter
164
+
value. For this API the only supported value is `closest`.
127
165
schema:
128
166
type: string
129
167
enum: ["closest"]
@@ -146,7 +184,8 @@ paths:
146
184
147
185
- name: Network-Access-Identifier
148
186
in: header
149
-
description: 3GPP network access identifier for the subscription being used by the device.
187
+
description: 3GPP network access identifier for the subscription being
description: MSISDN in E.164 format (starting with country code) of the mobile subscription being used by the device. Optionally prefixed with '+'.
198
+
description: MSISDN in E.164 format (starting with country code) of
199
+
the mobile subscription being used by the device. Optionally
200
+
prefixed with '+'.
160
201
schema:
161
202
type: string
162
203
pattern: '^\+?[0-9]{5,15}$'
163
204
164
205
responses:
165
206
"200":
166
-
description: Successful response, returning the closest MEC platform to the user device identified in the request header.
207
+
description: Successful response, returning the closest MEC platform
208
+
to the user device identified in the request header.
167
209
content:
168
210
application/json:
169
211
schema:
@@ -192,14 +234,22 @@ paths:
192
234
$ref: "#/components/responses/504GatewayTimeout"
193
235
tags:
194
236
- Discovery
195
-
summary: Returns the name of the MEC platform closest to user device identified in the request.
196
-
description: On receiving this request, the network will return the name of the MEC platform with the shortest network path to the end user device identified in the request.
237
+
summary: Returns the name of the MEC platform closest to user device
238
+
identified in the request.
239
+
description: On receiving this request, the network will return the name
240
+
of the MEC platform with the shortest network path to the end user
241
+
device identified in the request.
197
242
198
243
components:
199
244
securitySchemes:
200
245
oAuth2ClientCredentials:
201
246
type: oauth2
202
-
description: The Simple Edge Discovery API makes use of the OAUTH 2.0 client credentials grant, which is applicable for server-to-server use cases involving trusted partners or clients without any protected user data involved. In this method the API invoker client is registered as a confidential client with an authorization grant type of client_credentials.
247
+
description: The Simple Edge Discovery API makes use of the OAUTH 2.0
248
+
client credentials grant, which is applicable for server-to-server use
249
+
cases involving trusted partners or clients without any protected user
250
+
data involved. In this method the API invoker client is registered as a
251
+
confidential client with an authorization grant type of
252
+
client_credentials.
203
253
flows:
204
254
clientCredentials:
205
255
tokenUrl: "{tokenUrl}"
@@ -209,12 +259,17 @@ components:
209
259
type: array
210
260
items:
211
261
$ref: "#/components/schemas/MecPlatform"
212
-
description: A collection of MEC Platforms. For this Simple Edge Discovery API the collection will have at most one member (the closest MEC Platform to the user device indicated in the request).
262
+
description: A collection of MEC Platforms. For this Simple Edge Discovery
263
+
API the collection will have at most one member (the closest MEC
264
+
Platform to the user device indicated in the request).
213
265
additionalProperties: false
214
266
215
267
MecPlatform:
216
268
type: object
217
-
description: A MEC Platform, 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 platform).
269
+
description: A MEC Platform, uniquely identified by a combination of the
270
+
value of the Edge Resource Name object and the value of the Provider
271
+
object (the name of the cloud provider or operator hosting that
272
+
platform).
218
273
properties:
219
274
edgeCloudProvider:
220
275
$ref: "#/components/schemas/EdgeCloudProvider"
@@ -228,7 +283,8 @@ components:
228
283
229
284
EdgeResource:
230
285
description: |
231
-
Edge Resource Name - an identifier for an edge resource in the operator domain.
286
+
Edge Resource Name - an identifier for an edge resource in the operator
287
+
domain.
232
288
type: string
233
289
additionalProperties: false
234
290
@@ -243,7 +299,9 @@ components:
243
299
description: The HTTP status code.
244
300
message:
245
301
type: string
246
-
description: This parameter appears when there was an error. Human readable explanation specific to this occurrence of the problem.
302
+
description: This parameter appears when there was an error.
303
+
Human readable explanation specific to this occurrence of the
304
+
problem.
247
305
248
306
###################################
249
307
# RESPONSES
@@ -257,12 +315,17 @@ components:
257
315
$ref: "#/components/schemas/errorResponse"
258
316
examples:
259
317
InsufficientParameters:
260
-
description: Sufficient parameters must be specified to allow the target UE to be identified.
318
+
description: Sufficient parameters must be specified to allow the
319
+
target UE to be identified.
261
320
value:
262
321
{
263
322
"code": "INVALID_ARGUMENT",
264
323
"status": 400,
265
-
"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) ",
324
+
"message": "Insufficient parameters: At least one of
325
+
Network-Access-Identifier, Phone-Number or IP-Address must be
326
+
specified, or, the API must be called by a client on a
327
+
network-attached device (hence passing the source IP in the
328
+
request header) ",
266
329
}
267
330
InvalidExternalId:
268
331
value:
@@ -279,7 +342,9 @@ components:
279
342
"message": "Invalid Header Format: Phone-Number",
280
343
}
281
344
InvalidIP:
282
-
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.
345
+
description: This error will be returned if the IP address does
346
+
not have a valid format, or if the IP address is a private IPv4
347
+
address.
283
348
value:
284
349
{
285
350
"code": "INVALID_ARGUMENT",
@@ -298,7 +363,8 @@ components:
298
363
{
299
364
"code": "UNAUTHENTICATED",
300
365
"status": 401,
301
-
"message": "Request not authenticated due to missing, invalid, or expired credentials",
366
+
"message": "Request not authenticated due to missing, invalid,
367
+
or expired credentials",
302
368
}
303
369
304
370
403Forbidden:
@@ -313,7 +379,8 @@ components:
313
379
{
314
380
"code": "PERMISSION_DENIED",
315
381
"status": 403,
316
-
"message": "Client does not have sufficient permissions to perform this action",
382
+
"message": "Client does not have sufficient permissions to
383
+
perform this action",
317
384
}
318
385
319
386
404NotFound:
@@ -324,7 +391,8 @@ components:
324
391
$ref: "#/components/schemas/errorResponse"
325
392
examples:
326
393
SubscriberNotFound:
327
-
description: No device found for the specified parameters, meaning the closest MEC platform cannot be determined.
394
+
description: No device found for the specified parameters, meaning
395
+
the closest MEC platform cannot be determined.
328
396
value:
329
397
{
330
398
"code": "NOT_FOUND",
@@ -340,12 +408,14 @@ components:
340
408
$ref: "#/components/schemas/errorResponse"
341
409
examples:
342
410
MethodNotAllowed:
343
-
description: An HTTP verb other than GET has been used to try and access the resource.
411
+
description: An HTTP verb other than GET has been used to try and
412
+
access the resource.
344
413
value:
345
414
{
346
415
"code": "METHOD_NOT_ALLOWED",
347
416
"status": 405,
348
-
"message": "The request method is not supported by this resource",
417
+
"message": "The request method is not supported by this
418
+
resource",
349
419
}
350
420
351
421
406Unacceptable:
@@ -361,7 +431,8 @@ components:
361
431
{
362
432
"code": "NOT_ACCEPTABLE",
363
433
"status": 406,
364
-
"message": "The server cannot produce a response matching the content requested by the client through Accept-* headers",
434
+
"message": "The server cannot produce a response matching the
435
+
content requested by the client through Accept-* headers",
365
436
}
366
437
367
438
429TooManyRequests:
@@ -372,12 +443,12 @@ components:
372
443
$ref: "#/components/schemas/errorResponse"
373
444
examples:
374
445
TooManyRequests:
375
-
description: Access to the API has been temporarily blocked due to quota or spike arrest limits being reached.
446
+
description: Access to the API has been temporarily blocked due to
447
+
quota or spike arrest limits being reached.
376
448
value:
377
449
{
378
-
"code": "TOO_MANY_REQUESTS",
379
-
"status": 429,
380
-
"message": "Either out of resource quota or reaching rate limiting",
0 commit comments