openapi: 3.0.3
info:
  title: Simple Edge Discovery API
  version: 0.9.2
  description: |
    The Simple Edge Discovery API returns the name of the Edge Computing platform located at the shortest network path from a particular user device.
  
servers:
  - url: https://api-sandbox.vf-dmp.engineering.vodafone.com
    description: "Sandbox"   
  - url: https://api.vf-dmp.engineering.vodafone.com
    description: "Production"

tags:
  - name: Discovery
    description: |
       Find the closest Edge computing platform to the user device.
  - name: Monitoring
    description: |
       Find the Health check of Discovery API.

paths:
  /eds/v0/mec-platforms:
    get:
      security: 
        - oAuth2ClientCredentials: []
      operationId: getMecplatforms
      parameters:
        - $ref: "#/components/parameters/vf-trace-transaction-id"
        - $ref: "#/components/parameters/X-Correlator"
        - name: filter
          in: query
          required: true
          description: Filter the Edge computing 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 device’s IP address allocated to the device. Ipv6 protocol is not supported for now. Example 84.125.93.10
          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: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MecPlatforms'
        "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: The Simple Edge Discovery API returns the name of the Edge Computing platform located at the shortest network path from a particular user device.
      description: On receiving this request, the network will return the name of the Edge Computing platform with the shortest network path to the end user device identified in the request.


  /eds/v0/ping:
    get:
      tags:
        - Monitoring
      summary: Check the upstream system is up and running.
      description: |-
        This API is to check the upstream system is up and running.

      security:
        - oAuth2ClientCredentials: []

      operationId: getPing

      parameters:
        - $ref: "#/components/parameters/vf-trace-transaction-id"

      responses:
        "200":
          description: "**OK**"
          content:
            application/json:
              examples:
                success_response:
                  value: {
                            "suffix": "/ping",
                            "client": "35.191.13.203",
                            "startTime": "2023-06-05T19:47:16.794Z",
                            "endTime": "2023-06-05T19:47:16.888Z",
                            "responseTime": 94,
                            "message": "PONG"
                          }
        "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'

  /eds/v0/status:
    get:
      tags:
        - Monitoring
      summary: Check the downstream system is up and running.
      description: |-
        This API is to check the downstream system is up and running.

      security:
        - oAuth2ClientCredentials: []

      operationId: getStatus

      parameters:
        - $ref: "#/components/parameters/vf-trace-transaction-id"

      responses:
        "200":
          description: "**OK**"
          content:
            application/json:
              examples:
                success_response:
                  value: {
                            "status": "OK",

                          }
        "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'


   
components:
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      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.
      flows:
        clientCredentials:
          tokenUrl: "/oauth2/v1/token"
          scopes: {}
  schemas:
    MecPlatforms:
      type: array
      items:
        $ref: '#/components/schemas/MecPlatform'
      description:  A collection of Edge Computing 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 Edge Computing 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"
        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: string
      additionalProperties: false  
  
    errorResponse:
      type: object
      properties:
        code:
          type: string
          description: A short, human-readable summary of the problem type.
        status:
          type: integer
          description: The HTTP status code
        message: 
          type: string
          description: This parameter appears when there was an error. Human readable explanation specific to this occurrence of the problem.
  parameters:
    vf-trace-transaction-id:
      name: vf-trace-transaction-id
      in: header
      required: false
      description: A unique identifier for each request (typically a GUID).  This is not defined as part of the standard, but it can be used by the Service Provider to set a value which could assist in troubleshooting.  Note - if this header is not set in the request, Vodafone generates this value upon receipt of the message and returns the value in the response as a header.
      schema:
        type: string   

    X-Correlator:
      name: X-Correlator
      in: header
      required: false
      description: Correlation UUID that will be included in the response to request. Example 42da5b19-457a-4d30-a5c4-038c62dccbb0
      schema:
        type: string        

###################################
# RESPONSES
####################################
  responses:
    400BadRequest: 
      description: Bad Request
      content:
        application/json:
          schema:
            $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/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/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 Edge Computing 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"
            }