Skip to content

Commit b971eda

Browse files
author
Nicola Cadenelli
committed
Enforce line-lenght at 80 characters
1 parent eba9585 commit b971eda

File tree

1 file changed

+136
-65
lines changed

1 file changed

+136
-65
lines changed

code/API_definitions/Discovery/simple_edge_discovery.yaml

+136-65
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
---
12
openapi: 3.0.3
23
info:
34
title: Simple Edge Discovery API
@@ -7,62 +8,92 @@ info:
78
---
89
# Summary
910
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.
1113
1214
# 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
3054
* `Network-Access-Identifier` (where available from the API host operator)
3155
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.
3360
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.
3562
3663
# Example requests:
3764
3865
Examples for all API clients:
3966
40-
GET /mec-platforms?filter=closest HTTP/1.1
41-
Host: example.com
42-
Accept: application/json
43-
Network-Access-Identifier: [email protected]
67+
GET /mec-platforms?filter=closest HTTP/1.1
68+
Host: example.com
69+
Accept: application/json
70+
Network-Access-Identifier: [email protected]
4471
45-
GET /mec-platforms?filter=closest HTTP/1.1
46-
Host: example.com
47-
Accept: application/json
48-
IP-Address: 84.125.93.10
72+
GET /mec-platforms?filter=closest HTTP/1.1
73+
Host: example.com
74+
Accept: application/json
75+
IP-Address: 84.125.93.10
4976
50-
GET /mec-platforms?filter=closest HTTP/1.1
51-
Host: example.com
52-
Accept: application/json
53-
Phone-Number: 441234567890
77+
GET /mec-platforms?filter=closest HTTP/1.1
78+
Host: example.com
79+
Accept: application/json
80+
Phone-Number: 441234567890
5481
5582
Example where API client is on a network-attached device:
5683
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
6087
6188
# Responses
6289
6390
## Success
6491
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:
6697
```
6798
{
6899
"MecPlatforms": [
@@ -75,16 +106,22 @@ info:
75106
```
76107
## Errors
77108
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.
79111
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.
81114
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.
83117
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.
85120
86121
# 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.
88125
89126
# Further info and support
90127
@@ -123,7 +160,8 @@ paths:
123160
- name: filter
124161
in: query
125162
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`.
127165
schema:
128166
type: string
129167
enum: ["closest"]
@@ -146,7 +184,8 @@ paths:
146184

147185
- name: Network-Access-Identifier
148186
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
188+
used by the device.
150189
example: "[email protected]"
151190
required: false
152191
schema:
@@ -156,14 +195,17 @@ paths:
156195
in: header
157196
example: "441234567890"
158197
required: false
159-
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 '+'.
160201
schema:
161202
type: string
162203
pattern: '^\+?[0-9]{5,15}$'
163204

164205
responses:
165206
"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.
167209
content:
168210
application/json:
169211
schema:
@@ -192,14 +234,22 @@ paths:
192234
$ref: "#/components/responses/504GatewayTimeout"
193235
tags:
194236
- 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.
197242

198243
components:
199244
securitySchemes:
200245
oAuth2ClientCredentials:
201246
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.
203253
flows:
204254
clientCredentials:
205255
tokenUrl: "{tokenUrl}"
@@ -209,12 +259,17 @@ components:
209259
type: array
210260
items:
211261
$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).
213265
additionalProperties: false
214266

215267
MecPlatform:
216268
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).
218273
properties:
219274
edgeCloudProvider:
220275
$ref: "#/components/schemas/EdgeCloudProvider"
@@ -228,7 +283,8 @@ components:
228283

229284
EdgeResource:
230285
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.
232288
type: string
233289
additionalProperties: false
234290

@@ -243,7 +299,9 @@ components:
243299
description: The HTTP status code.
244300
message:
245301
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.
247305

248306
###################################
249307
# RESPONSES
@@ -257,12 +315,17 @@ components:
257315
$ref: "#/components/schemas/errorResponse"
258316
examples:
259317
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.
261320
value:
262321
{
263322
"code": "INVALID_ARGUMENT",
264323
"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) ",
266329
}
267330
InvalidExternalId:
268331
value:
@@ -279,7 +342,9 @@ components:
279342
"message": "Invalid Header Format: Phone-Number",
280343
}
281344
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.
283348
value:
284349
{
285350
"code": "INVALID_ARGUMENT",
@@ -298,7 +363,8 @@ components:
298363
{
299364
"code": "UNAUTHENTICATED",
300365
"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",
302368
}
303369

304370
403Forbidden:
@@ -313,7 +379,8 @@ components:
313379
{
314380
"code": "PERMISSION_DENIED",
315381
"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",
317384
}
318385

319386
404NotFound:
@@ -324,7 +391,8 @@ components:
324391
$ref: "#/components/schemas/errorResponse"
325392
examples:
326393
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.
328396
value:
329397
{
330398
"code": "NOT_FOUND",
@@ -340,12 +408,14 @@ components:
340408
$ref: "#/components/schemas/errorResponse"
341409
examples:
342410
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.
344413
value:
345414
{
346415
"code": "METHOD_NOT_ALLOWED",
347416
"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",
349419
}
350420

351421
406Unacceptable:
@@ -361,7 +431,8 @@ components:
361431
{
362432
"code": "NOT_ACCEPTABLE",
363433
"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",
365436
}
366437

367438
429TooManyRequests:
@@ -372,12 +443,12 @@ components:
372443
$ref: "#/components/schemas/errorResponse"
373444
examples:
374445
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.
376448
value:
377449
{
378-
"code": "TOO_MANY_REQUESTS",
379-
"status": 429,
380-
"message": "Either out of resource quota or reaching rate limiting",
450+
"code": "TOO_MANY_REQUESTS", "status": 429, "message": "Either
451+
out of resource quota or reaching rate limiting",
381452
}
382453

383454
500InternalServerError:

0 commit comments

Comments
 (0)