From 6e17a5e83e2cdd0efc929ed1f039b663a6850e3d Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Fri, 11 Aug 2023 15:57:03 +0100 Subject: [PATCH 1/5] Aligned with commonalities * Unused parameters removed * Unused resource types removed * `filter` parameter added (to future-proof `GET /mecplatforms` with no filter as a request to read the collection resource * URI changed to kebab-case * OperationId updated to Camel Case * Identifiers moved to header for security reasons (per Device Identifier API) * Basepath updated including major version * Standard error codes added * Documentation simplified and examples added --- .../Discovery/simple_edge_discovery.yaml | 713 +++++++++--------- 1 file changed, 374 insertions(+), 339 deletions(-) diff --git a/code/API_definitions/Discovery/simple_edge_discovery.yaml b/code/API_definitions/Discovery/simple_edge_discovery.yaml index 965089d0..157b0c3f 100644 --- a/code/API_definitions/Discovery/simple_edge_discovery.yaml +++ b/code/API_definitions/Discovery/simple_edge_discovery.yaml @@ -1,392 +1,427 @@ openapi: 3.0.0 info: - title: Simple MEC Discovery API - version: 0.9.0 + title: Simple Edge Discovery API + version: 0.9.1 description: | - # Find your nearest MEC platform + # Find the closest MEC platform --- - Network operators will typically have multiple MEC sites in a given territory. Connecting your application to a server on the closest MEC platform means the lowest latency - however, the physical location of a user is not an accurate match to the closest MEC site, due to the way operator networks are configured. This API returns the MEC platforms with the _shortest network path_ to the client making the request, and hence the lowest propagation delay. - * If you have a server instance deployed there, connect to it to gain the lowest latency - * Or if not, you may wish to deploy an instance there using the APIs of the cloud provider supporting that zone. + # Summary + + The Simple Edge Discovery API returns the name of the closest operator MEC platform to a particular user device. + + # 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. + + Once you have the name of the closest MEC platform to the user device, you may: + + * connect your application client to your 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. + * or, if you have no instance on that MEC platform, you may wish to deploy one there. + + # Usage + + The API defines a single service endpoint `/mecplatforms?filter=closest`. To call this endpoint, the API consumer must first obtain a valid OAuth2 token from the token endpoint, which is then passed as an `Authorization` header. + + The API consumer must also pass at least one of the available mobile subscription identifiers as a 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` + * `Network-Access-Identifier` (where available from the API host operator) + + The Simple Edge Discovery 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. + * if you call the API from a device attached to the operator network, you may omit the explicit device identifier (see below) 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. + * if you call the API from a server, you must explicitly pass a device identifier in the request header (one of `Network-Access-Identifier`, or `Phone-Number`, or `IP-Address`) + + # Example requests: + + Examples for all API clients: + + GET /mec-platforms?filter=closest HTTP/1.1 + Host: example.com + Accept: application/json + Network-Access-Identifier: 4d596ac1-7822-4927-a3c5-d72e1f922c94@domain.com + + GET /mec-platforms?filter=closest HTTP/1.1 + 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 + Host: example.com + Accept: application/json + + # Responses + + ## Success + + 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 Ern (Edge Resource Name) object is the name of the closest MEC platform to the user device. An example of this JSON object is as follows: + ``` + { + "MecPlatforms": [ + {"Ern": "eu-west-2-wl1-man-wlz-1"} + ] + } + ``` + ## Errors + + If the authentication token is not valid, a `401 UNAUTHENTICATED` error is returned + + If the mobile subscription parameters contain a formatting error, a `400 INVALID_ARGUMENT` error is returned. + + If the mobile subscription cannot be identified from the provided parameters, a `404 NOT_FOUND` error is returned. + + Any more general service failures will result in an error in the `5xx`range with an explanation. + + # Further info and support + - This API is intended to be called by a client application hosted on a UE attached to the operator network. _Note that the API parameters have been listed in this 'simple API' to align with the full API, but are optional and may not be supported by the API server_ --- + contact: + email: sp-edc@lists.camaraproject.org license: name: Apache 2.0 - url: 'http://www.apache.org/licenses/LICENSE-2.0.html' + url: https://www.apache.org/licenses/LICENSE-2.0.html +externalDocs: + description: Product documentation at CAMARA + url: https://github.com/camaraproject/EdgeCloud + servers: - # Added by API Auto Mocking Plugin - - description: SwaggerHub API Auto Mocking - url: https://virtserver.swaggerhub.com/alphatest/SimpleAPI/1.1.2 + - url: "{apiRoot}/{basePath}" + variables: + apiRoot: + default: https://localhost:443 + description: API root + basePath: + default: eds/v0 + description: Base path for the Simple Edge Discovery API tags: - name: Discovery description: | - Find the closest MEC platform to the UE (user equipment) + Find the closest MEC platform to the user device. paths: - /: - get: - responses: - '200': - description: Bookmark - content: - application/json: - schema: - title: getResourcesResponse - type: object - properties: - resources: - type: array - items: - $ref: '#/components/schemas/Resources' - links: - type: array - items: - oneOf: - - $ref: '#/components/schemas/LinksCommon' - '401': - $ref: '#/components/responses/Unauthorized' - default: - $ref: '#/components/responses/Unexpected' - tags: - - Discovery - operationId: bookmark - summary: API bookmark - description: API bookmark - - /mecplatforms: + /mec-platforms: get: - operationId: get-mecplatforms + security: + - oAuth2ClientCredentials: [] + operationId: getMecplatforms parameters: - - $ref: '#/components/parameters/region' - - $ref: '#/components/parameters/zone' - - $ref: '#/components/parameters/serviceProfileId' - - $ref: '#/components/parameters/subscriberDensity' - - $ref: '#/components/parameters/UEIdentityType' - - $ref: '#/components/parameters/UEIdentity' + - name: filter + in: query + required: true + description: filter the MEC Platforms according to the parameter value. For this API the only supported value is `closest` + schema: + type: string + enum: [ + "closest" + ] + + - name: IP-Address + in: header + required: false + description: The public IP allocated to the device. If an IPv4 address is specified, the public port must also be specified in the "Port" header + examples: + ipv4: + value: "84.125.93.10" + ipv6: + value: "2001:db8:85a3:8d3:1319:8a2e:370:7344" + 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})))$' + - name: Network-Access-Identifier + in: header + 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 + - name: Phone-Number + in: header + 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}$' + responses: - '200': - description: MEC platforms matching query parameters - content: - application/json: - schema: - title: GetMECPlatformsResponse - type: object - properties: - MECPlatforms: - type: array - items: - $ref: '#/components/schemas/ResourcesMecPlatform' - links: - type: array - items: - oneOf: - - $ref: '#/components/schemas/LinksAllMecPlatforms' - - $ref: '#/components/schemas/LinksCommon' - '401': - $ref: '#/components/responses/Unauthorized' - default: - $ref: '#/components/responses/Unexpected' + "200": + $ref: '#/components/responses/200OK' + "400": + $ref: '#/components/responses/400BadRequest' + "401": + $ref: '#/components/responses/401Unauthorized' + "403": + $ref: '#/components/responses/403Forbidden' + "404": + $ref: '#/components/responses/404NotFound' + "405": + $ref: '#/components/responses/405MethodNotAllowed' + "406": + $ref: '#/components/responses/406Unacceptable' + "429": + $ref: '#/components/responses/429TooManyRequests' + "500": + $ref: '#/components/responses/500InternalServerError' + "502": + $ref: '#/components/responses/502BadGateway' + "503": + $ref: '#/components/responses/503ServiceUnavailable' + "504": + $ref: '#/components/responses/504GatewayTimeout' tags: - Discovery - summary: Returns the name of the closest MEC platform(s) to the UE that sent the request. - description: ON receiving this request, the network will calculate which of its MEC platforms have the shortest network path to the UE (terminal) from which the request was made. + summary: Returns the name of the MEC platform closest to user device identified in the request. + 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. components: + securitySchemes: + oAuth2ClientCredentials: + type: oauth2 + description: This API uses OAuth 2 with the client credentials grant flow. + flows: + clientCredentials: + tokenUrl: "{tokenUrl}" + scopes: {} schemas: - Resources: + MecPlatforms: type: array items: - oneOf: - - $ref: '#/components/schemas/LinksAllMecPlatforms' + $ref: '#/components/schemas/EdgeResource' + description: The name of the MEC Platform closest to the network-attached user device identified in the request. additionalProperties: false - ResourcesMecPlatform: + + EdgeResource: + description: | + Edge Resource Name - an identifier for an edge reource in the operator domain type: object properties: - ern: - $ref: '#/components/schemas/TypesEdgeResource' - zone: - $ref: '#/components/schemas/TypesZoneId' - region: - $ref: '#/components/schemas/TypesRegionId' - status: - description: Status of the MEC Platform (default is 'unknown') + Ern: type: string - enum: - - active - - inactive - - unknown - default: unknown - properties: - type: array - items: - type: object - properties: - type: - type: string - data: - type: object - additionalProperties: false - - TypesEdgeResource: - description: | - An object defined by the service provider representing an edge resource within its network domain, such as a MEC Platform. The string contains colon-separated metadata in the form ern::::: - type: string - additionalProperties: false - TypesZoneId: - description: | - Unique identifier representing a zone - type: string - additionalProperties: false - TypesRegionId: - description: | - Unique identifier representing a region - type: string - additionalProperties: false - TypesSuccess: + additionalProperties: false + + successResponse: type: object properties: - code: - type: string - message: - type: string - links: - $ref: '#/components/schemas/LinksCommon' - required: - - code - - message - - links - additionalProperties: false - TypesError: + MecPlatforms: + $ref: '#/components/schemas/MecPlatforms' + + errorResponse: type: object properties: code: type: string - message: + description: A short, human-readable summary of the problem type + status: + type: integer + description: The HTTP status code + message: type: string - links: - $ref: '#/components/schemas/LinksCommon' - required: - - code - - message - - links - additionalProperties: false - TypesUEIdentityType: - description: Type of User Equipment identifier used in `UEIdentity`. - type: string - enum: - - IPAddress - - MSISDN - - IMEI - - MDN - - GPSI - TypesUEIdentity: - description: Identifier value for User Equipment. The type of identifier is defined by the 'UEIdentityType' parameter. - type: string -########################################### -# LINKS -########################################### - LinksAllMecPlatforms: - type: object - readOnly: true - properties: - link: - type: object - properties: - rel: - type: string - pattern: ListMECPlatforms - example: ListMECPlatforms - method: - type: string - pattern: get - example: get - href: - type: string - pattern: '\/mecplatforms' - example: /mecplatforms - required: - - href - - rel - - method - additionalProperties: false - - LinksSelf: - type: object - readOnly: true - properties: - link: - type: object - properties: - rel: - type: string - pattern: self - example: self - method: - type: string - pattern: get - example: get - href: - type: string - format: uri - required: - - href - - rel - - method - additionalProperties: false - LinksVersionHistory: - type: object - readOnly: true - properties: - link: - type: object - properties: - rel: - type: string - pattern: version-history - example: version-history - method: - type: string - pattern: get - example: get - href: - type: string - format: uri - required: - - href - - rel - - method - additionalProperties: false - LinksTermsOfService: - type: object - readOnly: true - properties: - link: - type: object - properties: - rel: - type: string - pattern: terms-of-service - example: terms-of-service - method: - type: string - pattern: get - example: get - href: - type: string - format: uri - required: - - href - - rel - - method - additionalProperties: false - LinksBookmark: - type: object - readOnly: true - properties: - link: - type: object - properties: - rel: - type: string - pattern: bookmark - example: bookmark - method: - type: string - pattern: get - example: get - href: - type: string - format: uri - required: - - href - - rel - - method - additionalProperties: false - LinksCommon: - type: array - readOnly: true - items: - oneOf: - - $ref: '#/components/schemas/LinksSelf' - - $ref: '#/components/schemas/LinksVersionHistory' - - $ref: '#/components/schemas/LinksTermsOfService' - - $ref: '#/components/schemas/LinksBookmark' + description: This parameter appears when there was an error. Human readable explanation specific to this occurrence of the problem + -################################ -# PARAMETERS -################################ - - parameters: - region: - name: region - description: MEC region ID - in: query - required: false - schema: - type: string - zone: - name: zone - description: MEC zone ID - in: query - required: false - schema: - type: string - serviceProfileId: - name: serviceProfileId - description: service profile identifier - in: query - required: false - schema: - type: string - subscriberDensity: - name: subscriberDensity - description: Minimum number of 4G/5G subscribers per square kilometer. - in: query - required: false - schema: - type: integer - UEIdentityType: - name: ueIdentityType - description: Type of User Equipment identifier used in `UEIdentity`. - in: query - required: false - schema: - $ref: '#/components/schemas/TypesUEIdentityType' - UEIdentity: - name: ueIdentity - description: Identifier value for User Equipment. The type of identifier is defined by the UEIdentityType parameter. - in: query - required: false - schema: - $ref: '#/components/schemas/TypesUEIdentity' ################################### # RESPONSES #################################### responses: - OK: - description: HTTP 200 OK + 200OK: + description: Closest MEC platform to the provided user device identifier content: application/json: schema: - $ref: '#/components/schemas/TypesSuccess' - Unauthorized: - description: HTTP 401 Unauthorized + $ref: '#/components/schemas/successResponse' + + + 400BadRequest: + description: Bad Request content: application/json: schema: - $ref: '#/components/schemas/TypesError' - NotFound: - description: HTTP 404 The specified resource was not found + $ref: '#/components/schemas/errorResponse' + examples: + InsufficientParameters: + description: Sufficient parameters must be specified to allow the target UE to be identified + value: + { + "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) " + } + InvalidExternalId: + value: + { + "code": "INVALID_ARGUMENT", + "status": 400, + "message": "Invalid Header Format: Network-Access-Identifier" + } + InvalidMSISDN: + value: + { + "code": "INVALID_ARGUMENT", + "status": 400, + "message": "Invalid Header Format: Phone-Number" + } + InvalidIP: + 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 + value: + { + "code": "INVALID_ARGUMENT", + "status": 400, + "message": "Invalid Header Format: IP-Address" + } + 401Unauthorized: + description: Unauthorized content: application/json: schema: - $ref: '#/components/schemas/TypesError' - Unexpected: - description: HTTP 500 Internal Server Error + $ref: '#/components/schemas/errorResponse' + examples: + InvalidCredentials: + value: + { + "code": "UNAUTHENTICATED", + "status": 401, + "message": "Request not authenticated due to missing, invalid, or expired credentials" + } + + 403Forbidden: + description: Forbidden content: application/json: schema: - $ref: '#/components/schemas/TypesError' - + $ref: '#/components/schemas/errorResponse' + examples: + InsufficientPermissions: + value: + { + "code": "PERMISSION_DENIED", + "status": 403, + "message": "Client does not have sufficient permissions to perform this action" + } + + 404NotFound: + description: Subscriber Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + examples: + SubscriberNotFound: + description: No device found for the specified parameters, meaning the closest MEC platform cannot be determined. + value: + { + "code": "NOT_FOUND", + "status": 404, + "message": "No device found for the specified parameters" + } + + 405MethodNotAllowed: + description: Method Not Allowed + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + examples: + MethodNotAllowed: + description: An HTTP verb other than GET has been used to try and access the resource + value: + { + "code": "METHOD_NOT_ALLOWED", + "status": 405, + "message": "The request method is not supported by this resource" + } + + 406Unacceptable: + description: Not Acceptable + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + examples: + NotAcceptable: + description: A response format other than JSON has been requested + value: + { + "code": "NOT_ACCEPTABLE", + "status": 406, + "message": "The server cannot produce a response matching the content requested by the client through Accept-* headers" + } + + 429TooManyRequests: + description: Too Many Requests + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + examples: + TooManyRequests: + description: Access to the API has been temporarily blocked due to quota or spike arrest limits being reached + value: + { + "code": "TOO_MANY_REQUESTS", + "status": 429, + "message": "Either out of resource quota or reaching rate limiting" + } + + 500InternalServerError: + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + { + "code": "INTERNAL", + "status": 500, + "message": "The service is currently not available" + } + + 502BadGateway: + description: Bad Gateway + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + { + "code": "BAD_GATEWAY", + "status": 502, + "message": "The service is currently not available" + } + + 503ServiceUnavailable: + description: Service Unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + { + "code": "UNAVAILABLE", + "status": 503, + "message": "The service is currently not available" + } + + 504GatewayTimeout: + description: Gateway Time-Out + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse' + example: + { + "code": "TIMEOUT", + "status": 504, + "message": "The service is currently not available" + } From 500d4b42757ac465a165a8fc7fb4f77ac335647f Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Tue, 15 Aug 2023 12:06:55 +0100 Subject: [PATCH 2/5] Update simple_edge_discovery.yaml 1. made `MecPlatforms` an array of `MecPlatform`. Only one `MecPlatform` is returned for this Simple EDS API but this allows extensibility 2. Added the Provider as context to the Ern (name of closest MEC Platform) as there is no agreed globally unique identifier for a MEC Platform 3. Simplified the introduction. --- .../Discovery/simple_edge_discovery.yaml | 65 ++++++++++++------- 1 file changed, 41 insertions(+), 24 deletions(-) diff --git a/code/API_definitions/Discovery/simple_edge_discovery.yaml b/code/API_definitions/Discovery/simple_edge_discovery.yaml index 157b0c3f..e966ee0a 100644 --- a/code/API_definitions/Discovery/simple_edge_discovery.yaml +++ b/code/API_definitions/Discovery/simple_edge_discovery.yaml @@ -19,17 +19,20 @@ info: # Usage - The API defines a single service endpoint `/mecplatforms?filter=closest`. To call this endpoint, the API consumer must first obtain a valid OAuth2 token from the token endpoint, which is then passed as an `Authorization` header. + 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. - The API consumer must also pass at least one of the available mobile subscription identifiers as a header: + 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. - * `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` - * `Network-Access-Identifier` (where available from the API host operator) - The Simple Edge Discovery 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. - * if you call the API from a device attached to the operator network, you may omit the explicit device identifier (see below) 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. - * if you call the API from a server, you must explicitly pass a device identifier in the request header (one of `Network-Access-Identifier`, or `Phone-Number`, or `IP-Address`) + 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. + + # Example requests: @@ -63,9 +66,12 @@ info: 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 Ern (Edge Resource Name) object is the name of the closest MEC platform to the user device. An example of this JSON object is as follows: ``` { - "MecPlatforms": [ - {"Ern": "eu-west-2-wl1-man-wlz-1"} - ] + "MecPlatforms": [ + { + "Provider": "AWS", + "Ern": "eu-west-2-wl1-man-wlz-1 + } + ] } ``` ## Errors @@ -138,6 +144,7 @@ paths: 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})))$' + - name: Network-Access-Identifier in: header description: 3GPP network access identifier for the subscription being used by the device @@ -195,28 +202,38 @@ components: tokenUrl: "{tokenUrl}" scopes: {} schemas: + successResponse: + type: object + properties: + MecPlatforms: + $ref: '#/components/schemas/MecPlatforms' + MecPlatforms: type: array items: - $ref: '#/components/schemas/EdgeResource' + $ref: '#/components/schemas/MecPlatform' description: The name of the MEC Platform closest to the network-attached user device identified in the request. additionalProperties: false + + MecPlatform: + type: object + properties: + Provider: + $ref: "#/components/schemas/Provider" + Ern: + $ref: "#/components/schemas/EdgeResource" + + Provider: + description: | + The company name of the MEC Platform provider + type: string EdgeResource: description: | Edge Resource Name - an identifier for an edge reource in the operator domain - type: object - properties: - Ern: - type: string - additionalProperties: false - - successResponse: - type: object - properties: - MecPlatforms: - $ref: '#/components/schemas/MecPlatforms' - + type: string + additionalProperties: false + errorResponse: type: object properties: From 1030ec923bd3d38fbfb55b2fea5595e908f829f1 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Mon, 21 Aug 2023 14:07:15 +0100 Subject: [PATCH 3/5] Code typo fix added missing quote mark in example success response --- code/API_definitions/Discovery/simple_edge_discovery.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/Discovery/simple_edge_discovery.yaml b/code/API_definitions/Discovery/simple_edge_discovery.yaml index e966ee0a..5a79140f 100644 --- a/code/API_definitions/Discovery/simple_edge_discovery.yaml +++ b/code/API_definitions/Discovery/simple_edge_discovery.yaml @@ -69,7 +69,7 @@ info: "MecPlatforms": [ { "Provider": "AWS", - "Ern": "eu-west-2-wl1-man-wlz-1 + "Ern": "eu-west-2-wl1-man-wlz-1" } ] } From 1a3282fc4ee73693f10f76fbef6a362abacd03a4 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Mon, 21 Aug 2023 14:23:50 +0100 Subject: [PATCH 4/5] Explained that provider:ern tuple must be unique --- .../Discovery/simple_edge_discovery.yaml | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/code/API_definitions/Discovery/simple_edge_discovery.yaml b/code/API_definitions/Discovery/simple_edge_discovery.yaml index 5a79140f..f883d778 100644 --- a/code/API_definitions/Discovery/simple_edge_discovery.yaml +++ b/code/API_definitions/Discovery/simple_edge_discovery.yaml @@ -32,7 +32,7 @@ info: * 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 # Example requests: @@ -63,7 +63,7 @@ info: ## Success - 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 Ern (Edge Resource Name) object is the name of the closest MEC platform to the user device. An example of this JSON object is as follows: + 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 `Provider` object is the name of the operator or cloud provider of the MEC Platform. `Ern` (Edge Resource Name) object is the name of the closest MEC platform to the user device. An example of this JSON object is as follows: ``` { "MecPlatforms": [ @@ -84,9 +84,11 @@ info: Any more general service failures will result in an error in the `5xx`range with an explanation. - # Further info and support - + # Note for Simple Edge API publishers + The API publisher (i.e. the operator implementation) must ensure that the tuple of Provider+Ern in the success reponse is unique. + # Further info and support + --- contact: email: sp-edc@lists.camaraproject.org From 1505ff7e694f3810ebdf1194f927bba5d8a6c471 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Thu, 31 Aug 2023 16:37:34 +0000 Subject: [PATCH 5/5] Updated 200 response per PR discussion --- .../Discovery/simple_edge_discovery.yaml | 23 ++++++------------- 1 file changed, 7 insertions(+), 16 deletions(-) diff --git a/code/API_definitions/Discovery/simple_edge_discovery.yaml b/code/API_definitions/Discovery/simple_edge_discovery.yaml index f883d778..1b69b0f1 100644 --- a/code/API_definitions/Discovery/simple_edge_discovery.yaml +++ b/code/API_definitions/Discovery/simple_edge_discovery.yaml @@ -166,7 +166,11 @@ paths: responses: "200": - $ref: '#/components/responses/200OK' + description: Successful reaponse, returning the closest MEC platform to the user device identified in the request header + content: + application/json: + schema: + $ref: '#/components/schemas/MecPlatforms' "400": $ref: '#/components/responses/400BadRequest' "401": @@ -204,21 +208,16 @@ components: tokenUrl: "{tokenUrl}" scopes: {} schemas: - successResponse: - type: object - properties: - MecPlatforms: - $ref: '#/components/schemas/MecPlatforms' - MecPlatforms: type: array items: $ref: '#/components/schemas/MecPlatform' - description: The name of the MEC Platform closest to the network-attached user device identified in the request. + 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). additionalProperties: false MecPlatform: type: object + description: A MEC Platform, uniquely identified by a combination of the value of the ERN (Edge Resource Name) object and the value of the Provider object (the name of the cloud provider or operator hosting that platform). properties: Provider: $ref: "#/components/schemas/Provider" @@ -254,14 +253,6 @@ components: # RESPONSES #################################### responses: - 200OK: - description: Closest MEC platform to the provided user device identifier - content: - application/json: - schema: - $ref: '#/components/schemas/successResponse' - - 400BadRequest: description: Bad Request content: