Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Simple edge discovery: spelling and linting #223

Merged
merged 3 commits into from
Mar 25, 2024
Merged

Simple edge discovery: spelling and linting #223

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
500e127
Spelling and autolinting
Mar 21, 2024
eba9585
Solve some markdown warnings
Mar 21, 2024
b971eda
Enforce line-lenght at 80 characters
Mar 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 34 additions & 24 deletions code/API_definitions/Discovery/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,50 +1,60 @@
# Edge Discovery APIs

## Simple Discovery API
This API allows a client application to discover the closest MEC platform to the UE hosting the client application. 'Closest' means 'shorteset network path' as that will give the shortest propogation distance, which is a major factor in latency.

This API allows a client application to discover the closest MEC platform to the UE hosting the client application. 'Closest' means 'shortest network path' as that will give the shortest propagation distance, which is a major factor in latency.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should it be "platforms"? Plural as the API returns the array of platforms.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should it be "platforms"? Plural as the API returns the array of platforms.

No, Simple Edge Discovery returns only the closest platform. For convenience this is returned as an array with one member, to allow easier portability of parsing code to the other Edge Cloud API that will return multiple platforms.


## MEC Experience Management and Exposure API

This API allows a developer to:

- discover available MEC platforms, ranked by proximity to a UE.
- read the state (availability and capabilities) of an operator's various MEC platforms.
- register a service profile (a description of the developer's edge service) with the MEC operator
- register the deployed service endpoints with the MEC operator, which allows the closest service endpoint to be discovered at runtime
- register a service profile (a description of the developer's edge service) with the MEC operator.
- register the deployed service endpoints with the MEC operator, which allows the closest service endpoint to be discovered at runtime.

The API will also support the following capabilities:
- events(such as change of status of a MEC platform or another event which could affect their service)
The API will also support the following capabilities:

- events(such as change of status of a MEC platform or another event which could affect their service).
- subscription to notification of events.

# Mapping to the list of intents
## Mapping to the list of intents

These APIs fulfil the ['discovery' intents](https://github.com/camaraproject/EdgeCloud/blob/main/documentation/SupportingDocuments/Harmonisation%20of%20APIs/describing%20and%20harmonising%20the%20Edge%20APIs.md)

*Simple Edge Discovery* fulfils a single intent, "4. I can discover the closest MEC platform to a specific terminal (closest in terms of shortest network path)"
*Simple Edge Discovery* fulfils a single intent, "4. I can discover the closest MEC platform to a specific terminal (closest in terms of shortest network path)"

*MEC Exposure and Experience Management* is a more comprehensive discovery API and fulfils the following intents:

### Developer intents
#### Provisioning intents
1. “I can retrieve a list of the operator’s MECs and their status, ordering the results by location and filtering by status (active/inactive/unknown)”
2. "I can discover the capabilities/resources available at an operator’s MEC: CPU, Memory, Storage, GPU"
3. "I can discover the geographical regions covered by the operators MECs"
4. "I can discover the closest MEC platform to a specific terminal (closest in terms of shortest network path)"

16. “I can ask the operator to provide the details of all the onboarded applications”
17. "I can ask the operator to inform about the application instance details e.g., communication endpoints, resource consumed etc"
#### Provisioning intents

1. "I can retrieve a list of the operator’s MECs and their status, ordering the results by location and filtering by status (active/inactive/unknown)"
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We have terms with alternate words e.g. here it says MECs but the API says MEC Platforms

2. "I can discover the capabilities/resources available at an operator’s MEC: CPU, Memory, Storage, GPU"
3. "I can discover the geographical regions covered by the operators MECs"
4. "I can discover the closest MEC platform to a specific terminal (closest in terms of shortest network path)"

16. "I can ask the operator to provide the details of all the on-boarded applications"
17. "I can ask the operator to inform about the application instance details e.g., communication endpoints, resource consumed etc"

#### Runtime intents
19. "I can discover the closest MEC platform to a particular terminal (closest in terms of shortest network path)"
20. "I can discover the optimal MEC platform for my application and a particular terminal, taking into account connectivity, shortest network path, cost, network load etc." (`A`)
21. "I can discover the optimal application service endpoint for a specific terminal, taking into account mobility events, connectivity, shortest network path, cost, network load, MEC platform load etc."
#### Runtime intents

19. "I can discover the closest MEC platform to a particular terminal (closest in terms of shortest network path)"
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here we have MEC platform while at line 33 it is MECs

20. "I can discover the optimal MEC platform for my application and a particular terminal, taking into account connectivity, shortest network path, cost, network load etc." (`A`)
21. "I can discover the optimal application service endpoint for a specific terminal, taking into account mobility events, connectivity, shortest network path, cost, network load, MEC platform load etc."

### Operator intents

#### Provisioning intents
23. “I can publish an (ordered, filtered) list of my MECs, their coverage, capabilities and status” _(aligns with 1,2,3 in the developer intents)_
24. “I can map an application’s requirements to the best MEC for hosting it, based on application demands for CPU,Memory,Storage,GPU,bandwith,Network forecast, mobility” _(aligns with 4,5,8,9)_
#### Runtime intents
25. “I can inform the developer of any event which changes which MEC is optimal for their application and connected terminals” _(aligns with 6)_

## Notes:
23. "I can publish an (ordered, filtered) list of my MECs, their coverage, capabilities and status" *(aligns with 1,2,3 in the developer intents)*
24. "I can map an application’s requirements to the best MEC for hosting it, based on application demands for CPU, Memory, Storage, GPU, bandwidth, Network forecast, mobility" *(aligns with 4,5,8,9)*

#### Runtime intents

25. "I can inform the developer of any event which changes which MEC is optimal for their application and connected terminals" *(aligns with 6)*

## Notes

`A` this may not be the closest MEC, rather the 'best MEC for this job' which accounts for current MEC or network load, MEC copmute power and features etc.
`A` this may not be the closest MEC, rather the 'best MEC for this job' which accounts for current MEC or network load, MEC compute power and features etc.
23 changes: 11 additions & 12 deletions code/API_definitions/Discovery/simple_edge_discovery.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
openapi: 3.0.3

Check warning on line 1 in code/API_definitions/Discovery/simple_edge_discovery.yaml

View workflow job for this annotation

GitHub Actions / MegaLinter 

1:1 [document-start] missing document start "---"
info:
title: Simple Edge Discovery API
version: 0.9.3
Expand All @@ -7,7 +7,7 @@
---
# Summary

The Simple Edge Discovery API returns the name of the closest operator MEC platform to a particular user device.
The Simple Edge Discovery API returns the name of the closest operator MEC platform to a particular user device.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should it be "platforms"? Singular to Plural?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@gunjald I'm not changing the content or meaning of the API.
I'm just applying linting and spelling. These issues you comment need a dedicated PR.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok. Then we can leave this comment for now and will address it later as separate PR


# Purpose
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.
Expand All @@ -18,21 +18,20 @@
* or, if you have no instance on that MEC platform, you may wish to deploy one there.

# 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: `/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.


The API returns the closest MEC platform to a given device, so that device needs to be identifiable by the network:
* if you call the API from a server, you must explicitly pass one or more device identifiers in the HTTP request header:
* `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)
* `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, 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.

The provider of the MEC Platform may be an operator, or a cloud provider. The
The provider of the MEC Platform may be an operator, or a cloud provider. The

# Example requests:

Expand All @@ -47,12 +46,12 @@
Host: example.com
Accept: application/json
IP-Address: 84.125.93.10

GET /mec-platforms?filter=closest HTTP/1.1
Host: example.com
Accept: application/json
Phone-Number: 441234567890

Example where API client is on a network-attached device:

GET /mec-platforms?filter=closest HTTP/1.1
Expand Down Expand Up @@ -85,9 +84,9 @@
Any more general service failures will result in an error in the `5xx`range with an explanation.

# Note for Simple Edge API publishers
The API publisher (i.e. the operator implementation) must ensure that the tuple of edgeCloudProvider+edgeResourceName in the success reponse is unique.
The API publisher (i.e. the operator implementation) must ensure that the tuple of edgeCloudProvider+edgeResourceName in the success response is unique.

# Further info and support
# Further info and support

---
contact:
Expand Down Expand Up @@ -229,7 +228,7 @@

EdgeResource:
description: |
Edge Resource Name - an identifier for an edge reource in the operator domain.
Edge Resource Name - an identifier for an edge resource in the operator domain.
type: string
additionalProperties: false

Expand Down Expand Up @@ -263,7 +262,7 @@
{
"code": "INVALID_ARGUMENT",
"status": 400,
"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 netwok-attached device (hence passing the source IP in the request header) ",
"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) ",
}
InvalidExternalId:
value:
Expand Down
Loading