From aa7ff8e922111496566df6b25fcf40af5bbd0e61 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Tue, 18 Jul 2023 13:22:52 +0100 Subject: [PATCH 1/3] Create Simple_Edge_Discovery_User_story.md --- .../Simple_Edge_Discovery_User_story.md | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 documentation/API_documentation/Simple_Edge_Discovery_User_story.md diff --git a/documentation/API_documentation/Simple_Edge_Discovery_User_story.md b/documentation/API_documentation/Simple_Edge_Discovery_User_story.md new file mode 100644 index 00000000..bc5657cf --- /dev/null +++ b/documentation/API_documentation/Simple_Edge_Discovery_User_story.md @@ -0,0 +1,78 @@ +# Simple Edge Discovery (EDS) API User Story + +| **Item** | **Details** | +| ---- | ------- | +| ***Summary*** | As an application developer belonging to an enterprise, I want to request (using either my application server/backend service, or an HTTP application client on the end user terminal) the closest MEC Platform to a given end user's terminal | +| ***Roles, Actors and Scope*** | **Roles:** Customer:User
**Actors:** Application service providers, hyperscalers, application developers. The API does not explicitly handle consent management (expects that network information related to proximity of terminal to MEC platforms is not sensitive information ) and hence end users are not included as Actors. Should this change, the actor list will be extended with end users.
+ **Scope:** *Order To Activate (OTA)* \- Create/Remove/Get service instance (QoD session resource)\, get notification about the instance (QoD session resource) | +| ***Pre-conditions*** |The preconditions are listed below:
  1. The Customer:BusinessManager and Customer:Administrator have been onboarded to the CSP's API platform.
  2. The Customer:BusinessManager has successfully subscribed to the QoD product from the product catalog.
  3. The Customer:Administrator has onboarded the Customer:User to the platform.
  4. The Customer either owns the device subscriptions or has agreed to the terms and conditions of the CSP for managing consent of subscription owners.
  5. The means to get the access token are known to the Customer:User to ensure secure access of the API.| + +| ***Activities/Steps*** | **Starts when:** The customer application server|client makes a GET request to the EDS API to query the closest MEC platofrm to the end user terminal. The end user terminal is either implicitly identified (e.g. by its source IP when attached to a cellular network) or explicitly identified (the identity is passed in the request querystring)
    **Ends when:** The EDS API responds to the customer application server|client . | + +| ***Post-conditions*** | Optional - the customer may decide to act upon the information by connecting the end user application client to the application server instance hosted at the closest MEC, and/or spin up an application server instance at that closest MEC if not currently hosted there. | +| ***Exceptions*** | the network is unable to calculate the closest MEC to the end user terminal. An HTTP 404 response code will indicate an issue with the provided end user terminal identity and that the request should not be retried without correction. HTTP 500 indicates an internal network error and the request may be retried. | + +## API Workflows +### Simple Edge Discovery +#### Scenario 1: direct request from client on terminal device + +Constraints: +- Network: cellular (4G/5G) +- Application: none, browser or app calls API over HTTP +- Northbound Interface only (no 'UNI' client SDK required) + +Note: +- the MEC platform may be hosted by the operator or a 3rd party hyperscaler (in which case the developer will need an account with that hyperscaler to create instances) + + +```mermaid +sequenceDiagram + participant app + participant operator + participant developer server + participant MEC platform + Note over app,operator: PRE App on device attached
    to operator network + Note over developer server,operator: PRE App developer registered,
    authenticated and authorised + app->>operator: GET /mecplatforms + operator->>app: name of closest MEC platform + alt app has a local mapping of server endpoints to MEC platforms + app->>app: lookup app server endpoint (MEC platform name) + app->>operator: connect to app server endpoint + else no local mapping + app->>developer server: report closest MEC for app + opt spin up instance on closest MEC platform + developer server->>MEC platform: create instance(MEC platform name) + MEC platform->>developer server: instance endpoint + developer server->>app: instance endpoint + end + end +``` +#### Scenario 2: request from developer server + +Constraints: +- Network: WiFi or cellular (4G/5G) +- Application: none, browser or app calls API over HTTP +- Northbound Interface only (no 'UNI' client SDK required) +- Dependency: the call must include an identifier for the terminal (UE) for which 'closest MEC' is being calculated + +Note: the MEC platform may be hosted by the operator or a 3rd party hyperscaler (in which case the developer will need an account with that hyperscaler to create instances) + +```mermaid +sequenceDiagram + participant app + participant operator + participant developer server + participant MEC platform + Note over developer server,operator: PRE developer has acquired an identifier for the terminal in question + Note over developer server,operator: PRE App developer registered,
    authenticated and authorised + developer server->>operator: GET /mecplatforms?ueIdentityType={value}&ueIdentity={value} + operator->>developer server: name of closest MEC platform + opt inform app + developer server->>app: report closest MEC for app + end + opt spin up instance on closest MEC platform + developer server->> MEC platform: create instance(MEC platform name) + MEC platform->>developer server: instance endpoint + developer server->>app: instance endpoint + end +``` From 4d5ce2231d1ccfb9c0247ae24a61caf90ac4626a Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Tue, 25 Jul 2023 13:00:28 +0100 Subject: [PATCH 2/3] Update Simple_Edge_Discovery_User_story.md Fixed some copy/paste errors --- .../Simple_Edge_Discovery_User_story.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/documentation/API_documentation/Simple_Edge_Discovery_User_story.md b/documentation/API_documentation/Simple_Edge_Discovery_User_story.md index bc5657cf..a6bd8ad4 100644 --- a/documentation/API_documentation/Simple_Edge_Discovery_User_story.md +++ b/documentation/API_documentation/Simple_Edge_Discovery_User_story.md @@ -2,15 +2,15 @@ | **Item** | **Details** | | ---- | ------- | -| ***Summary*** | As an application developer belonging to an enterprise, I want to request (using either my application server/backend service, or an HTTP application client on the end user terminal) the closest MEC Platform to a given end user's terminal | -| ***Roles, Actors and Scope*** | **Roles:** Customer:User
    **Actors:** Application service providers, hyperscalers, application developers. The API does not explicitly handle consent management (expects that network information related to proximity of terminal to MEC platforms is not sensitive information ) and hence end users are not included as Actors. Should this change, the actor list will be extended with end users.
    - **Scope:** *Order To Activate (OTA)* \- Create/Remove/Get service instance (QoD session resource)\, get notification about the instance (QoD session resource) | -| ***Pre-conditions*** |The preconditions are listed below:
    1. The Customer:BusinessManager and Customer:Administrator have been onboarded to the CSP's API platform.
    2. The Customer:BusinessManager has successfully subscribed to the QoD product from the product catalog.
    3. The Customer:Administrator has onboarded the Customer:User to the platform.
    4. The Customer either owns the device subscriptions or has agreed to the terms and conditions of the CSP for managing consent of subscription owners.
    5. The means to get the access token are known to the Customer:User to ensure secure access of the API.| +| ***Summary*** | As an application developer belonging to an enterprise, I want to request (using either my application server/backend service, or an HTTP application client on the end user terminal) the closest MEC Platform to a given end user's terminal. | +| ***Roles, Actors and Scope*** | **Roles:** Customer:User
      **Actors:** Application service providers, network operators, application developers. The API does not explicitly handle consent management (expects that network information related to proximity of terminal to MEC platforms is not sensitive information ) and hence end users are not included as Actors. Should this change, the actor list will be extended with end users.
      + **Scope:** Get closest MEC platform to a target UE | +| ***Pre-conditions*** |The preconditions are listed below:
      1. The Customer:BusinessManager and Customer:Administrator have been onboarded to the CSP's API platform.
      2. The Customer:BusinessManager has successfully subscribed to the EDS product from the product catalog.
      3. The Customer:Administrator has onboarded the Customer:User to the platform.
      4. The Customer:User has obtained a valid identifier for the target UE.
        5. | -| ***Activities/Steps*** | **Starts when:** The customer application server|client makes a GET request to the EDS API to query the closest MEC platofrm to the end user terminal. The end user terminal is either implicitly identified (e.g. by its source IP when attached to a cellular network) or explicitly identified (the identity is passed in the request querystring)
        **Ends when:** The EDS API responds to the customer application server|client . | +| ***Activities/Steps*** | **Starts when:** The customer application server|client makes a GET request to the EDS API to query the closest MEC platform to the target UE (an end user terminal). The target UE is either implicitly identified (e.g. by its source IP when attached to a cellular network) or explicitly identified (the identity is passed in the request querystring)
        **Ends when:** The EDS API responds to the customer application server|client . | | ***Post-conditions*** | Optional - the customer may decide to act upon the information by connecting the end user application client to the application server instance hosted at the closest MEC, and/or spin up an application server instance at that closest MEC if not currently hosted there. | -| ***Exceptions*** | the network is unable to calculate the closest MEC to the end user terminal. An HTTP 404 response code will indicate an issue with the provided end user terminal identity and that the request should not be retried without correction. HTTP 500 indicates an internal network error and the request may be retried. | +| ***Exceptions*** | the network is unable to calculate the closest MEC to the end user terminal. An HTTP 500 response code will indicate an issue with the provided end user terminal identity and that the request should not be retried without correction. HTTP 500 indicates an internal network error and the request may be retried. | ## API Workflows ### Simple Edge Discovery From e270b528f8f9e2e8a9937f4b92680981b5d02a35 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Wed, 26 Jul 2023 13:20:11 +0100 Subject: [PATCH 3/3] Update Simple_Edge_Discovery_User_story.md Fixed formatting issues --- .../API_documentation/Simple_Edge_Discovery_User_story.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/documentation/API_documentation/Simple_Edge_Discovery_User_story.md b/documentation/API_documentation/Simple_Edge_Discovery_User_story.md index a6bd8ad4..d264a532 100644 --- a/documentation/API_documentation/Simple_Edge_Discovery_User_story.md +++ b/documentation/API_documentation/Simple_Edge_Discovery_User_story.md @@ -4,11 +4,9 @@ | ---- | ------- | | ***Summary*** | As an application developer belonging to an enterprise, I want to request (using either my application server/backend service, or an HTTP application client on the end user terminal) the closest MEC Platform to a given end user's terminal. | | ***Roles, Actors and Scope*** | **Roles:** Customer:User
        **Actors:** Application service providers, network operators, application developers. The API does not explicitly handle consent management (expects that network information related to proximity of terminal to MEC platforms is not sensitive information ) and hence end users are not included as Actors. Should this change, the actor list will be extended with end users.
        - **Scope:** Get closest MEC platform to a target UE | + **Scope:** | Get closest MEC platform to a target UE | | ***Pre-conditions*** |The preconditions are listed below:
        1. The Customer:BusinessManager and Customer:Administrator have been onboarded to the CSP's API platform.
        2. The Customer:BusinessManager has successfully subscribed to the EDS product from the product catalog.
        3. The Customer:Administrator has onboarded the Customer:User to the platform.
        4. The Customer:User has obtained a valid identifier for the target UE.
          5. | - -| ***Activities/Steps*** | **Starts when:** The customer application server|client makes a GET request to the EDS API to query the closest MEC platform to the target UE (an end user terminal). The target UE is either implicitly identified (e.g. by its source IP when attached to a cellular network) or explicitly identified (the identity is passed in the request querystring)
          **Ends when:** The EDS API responds to the customer application server|client . | - +| ***Activities/Steps*** | **Starts when:** The customer application server/client makes a GET request to the EDS API to query the closest MEC platform to the target UE (an end user terminal). The target UE is either implicitly identified (e.g. by its source IP when attached to a cellular network) or explicitly identified (the identity is passed in the request querystring)
          **Ends when:** The EDS API responds to the customer application server|client . | | ***Post-conditions*** | Optional - the customer may decide to act upon the information by connecting the end user application client to the application server instance hosted at the closest MEC, and/or spin up an application server instance at that closest MEC if not currently hosted there. | | ***Exceptions*** | the network is unable to calculate the closest MEC to the end user terminal. An HTTP 500 response code will indicate an issue with the provided end user terminal identity and that the request should not be retried without correction. HTTP 500 indicates an internal network error and the request may be retried. |