BwManagementApi.yaml 19.4 KB
Newer Older
openapi: 3.1.0
Michel Roy's avatar
Michel Roy committed
  contact:
    url: https://forge.etsi.org/rep/mec/gs015-bandwith-mgmt-api
Michel Roy's avatar
Michel Roy committed
  title: 'ETSI GS MEC 015 Bandwidth Management API'
  version: 2.2.1
Michel Roy's avatar
Michel Roy committed
  description: The ETSI MEC ISG Bandwidth Management API described using OpenAPI.
admin_forge's avatar
admin_forge committed
    name: BSD-3-Clause
Michel Roy's avatar
Michel Roy committed
    url: 'https://forge.etsi.org/legal-matters'

  description: ETSI GS MEC015 V2.2.1 Traffic Management APIs
  url: 'https://www.etsi.org/deliver/etsi_gs/MEC/001_099/015/02.02.01_60/gs_MEC015v020201p.pdf'
servers:
Michel Roy's avatar
Michel Roy committed
  - url: 'https://localhost/bwm/v1'

tags:
- name: "bwm"
Michel Roy's avatar
Michel Roy committed
  /bw_allocations:
      tags:
Michel Roy's avatar
Michel Roy committed
      - "bwm"
Michel Roy's avatar
Michel Roy committed
      summary: "Retrieve information about a list of bandwidthAllocation resources"
      description: "Retrieves information about a list of bandwidthAllocation resources. Typically used in 'Get configured bandwidth allocation from Bandwidth Management Service' procedure as described in clause 6.2.5."
      operationId: "bandwidthAllocationListGET"
      parameters:
        - $ref: '#/components/parameters/Query.app_instance_id'
        - $ref: '#/components/parameters/Query.app_name'
        - $ref: '#/components/parameters/Query.session_id'
Michel Roy's avatar
Michel Roy committed
          description: "Upon success, a response body containing an array of the bandwidthAllocations is returned."
          content:
            application/json:
              schema:
Michel Roy's avatar
Michel Roy committed
                type: array
                items:
                  $ref: "#/components/schemas/BwInfo"
Michel Roy's avatar
Michel Roy committed
          $ref: "#/components/responses/400"
Michel Roy's avatar
Michel Roy committed
          $ref: '#/components/responses/403'
Michel Roy's avatar
Michel Roy committed
          $ref: '#/components/responses/404'
      tags:
Michel Roy's avatar
Michel Roy committed
      - "bwm"
Michel Roy's avatar
Michel Roy committed
      summary: "Create a bandwidthAllocation resource"
      description: "Used to create a bandwidthAllocation resource. Typically used in 'Register to Bandwidth Management Service' procedure as described in clause 6.2.1."
      operationId: "bandwidthAllocationPOST"
      parameters: []
      requestBody:
        description: "Entity body in the request contains BwInfo to be created."
        required: true
        content:
          application/json:
            schema:
Michel Roy's avatar
Michel Roy committed
              $ref: '#/components/schemas/BwInfo'
Michel Roy's avatar
Michel Roy committed
          description: "Upon success, the HTTP response shall include a 'Location' HTTP header that contains the resource URI of the created resource."
          content:
            application/json:
              schema:
Michel Roy's avatar
Michel Roy committed
                $ref: "#/components/schemas/BwInfo"
Michel Roy's avatar
Michel Roy committed
          $ref: "#/components/responses/400"
Michel Roy's avatar
Michel Roy committed
          $ref: '#/components/responses/403'
Michel Roy's avatar
Michel Roy committed
          $ref: '#/components/responses/404'
  /bw_allocations/{allocationId}:
      tags:
Michel Roy's avatar
Michel Roy committed
      - "bwm"
Michel Roy's avatar
Michel Roy committed
      summary: "Retrieve information about a specific bandwidthAllocation"
      description: "Retrieves information about a bandwidthAllocation resource. Typically used in 'Get configured bandwidth allocation from Bandwidth Management Service' procedure as described in clause 6.2.5."
      operationId: "bandwidthAllocationGET"
      parameters:
        - $ref: '#/components/parameters/Path.allocationId'
Michel Roy's avatar
Michel Roy committed
          description: "Used to indicate nonspecific success. The response body contains a representation of the resource."
          content:
            application/json:
              schema:
Michel Roy's avatar
Michel Roy committed
                $ref: "#/components/schemas/BwInfo"
Michel Roy's avatar
Michel Roy committed
          $ref: "#/components/responses/400"
Michel Roy's avatar
Michel Roy committed
          $ref: '#/components/responses/403'
Michel Roy's avatar
Michel Roy committed
          $ref: '#/components/responses/404'
      tags:
Michel Roy's avatar
Michel Roy committed
      - "bwm"
Michel Roy's avatar
Michel Roy committed
      summary: "Update the information about a specific bandwidthAllocation"
      description: "Updates the information about a bandwidthAllocation resource. As specified in ETSI GS MEC 009 [6], the PUT HTTP method has 'replace' semantics."
      operationId: "bandwidthAllocationPUT"
      requestBody:
        description: "BwInfo with updated information is included as entity body of the request."
        required: true
        content:
          application/json:
            schema:
Michel Roy's avatar
Michel Roy committed
              $ref: '#/components/schemas/BwInfo'
Michel Roy's avatar
Michel Roy committed
      parameters:
        - $ref: '#/components/parameters/Path.allocationId'
Michel Roy's avatar
Michel Roy committed
          description: "Used to indicate nonspecific success. The response body contains a representation of the resource."
          content:
            application/json:
              schema:
Michel Roy's avatar
Michel Roy committed
                $ref: "#/components/schemas/BwInfo"
Michel Roy's avatar
Michel Roy committed
          $ref: "#/components/responses/400"
Michel Roy's avatar
Michel Roy committed
          $ref: '#/components/responses/403'
Michel Roy's avatar
Michel Roy committed
          $ref: '#/components/responses/404'
Michel Roy's avatar
Michel Roy committed
          $ref: '#/components/responses/412'
      tags:
Michel Roy's avatar
Michel Roy committed
      - "bwm"
Michel Roy's avatar
Michel Roy committed
      summary: "Modify the information about a specific existing bandwidthAllocation by sending updates on the data structure"
      description: "Updates the information about a bandwidthAllocation resource. As specified in ETSI GS MEC 009 [6], the PATCH HTTP method updates a resource on top of the existing resource state by just including the changes ('deltas') in the request body."
      operationId: "bandwidthAllocationPATCH"
      requestBody:
        description: "Description of the changes to instruct the server how to modify the resource representation."
        required: true
        content:
          application/json:
            schema:
Michel Roy's avatar
Michel Roy committed
              $ref: '#/components/schemas/BwInfoDeltas'
Michel Roy's avatar
Michel Roy committed
      parameters:
        - $ref: '#/components/parameters/Path.allocationId'
Michel Roy's avatar
Michel Roy committed
          description: "Used to indicate nonspecific success. The response body contains a representation of the resource."
          content:
            application/json:
              schema:
Michel Roy's avatar
Michel Roy committed
                $ref: "#/components/schemas/BwInfo"
Michel Roy's avatar
Michel Roy committed
          $ref: "#/components/responses/400"
Michel Roy's avatar
Michel Roy committed
          $ref: '#/components/responses/403'
Michel Roy's avatar
Michel Roy committed
          $ref: '#/components/responses/404'
Michel Roy's avatar
Michel Roy committed
          $ref: '#/components/responses/412'
      tags:
Michel Roy's avatar
Michel Roy committed
      - "bwm"
Michel Roy's avatar
Michel Roy committed
      summary: "Remove a specific bandwidthAllocation"
      description: "Used in 'Unregister from Bandwidth Management Service' procedure as described in clause 6.2.3."
      operationId: "bandwidthAllocationDELETE"
      parameters:
        - $ref: '#/components/parameters/Path.allocationId'
Michel Roy's avatar
Michel Roy committed
          $ref: '#/components/responses/204'
Michel Roy's avatar
Michel Roy committed
          $ref: '#/components/responses/403'
Michel Roy's avatar
Michel Roy committed
          $ref: '#/components/responses/404'
components:
Michel Roy's avatar
Michel Roy committed
  responses:
Michel Roy's avatar
Michel Roy committed
      description: "Upon success, a response 204 No Content without any response body is returned."
Michel Roy's avatar
Michel Roy committed
      description: 'Bad Request : used to indicate that incorrect parameters were passed to the request.'
      content:
Michel Roy's avatar
Michel Roy committed
        application/problem+json:
Michel Roy's avatar
Michel Roy committed
          schema:
Michel Roy's avatar
Michel Roy committed
            $ref: '#/components/schemas/ProblemDetails'
Michel Roy's avatar
Michel Roy committed
      description: 'Forbidden :  operation is not allowed given the current status of the resource.'
      content:
Michel Roy's avatar
Michel Roy committed
        application/problem+json:
Michel Roy's avatar
Michel Roy committed
          schema:
Michel Roy's avatar
Michel Roy committed
            $ref: '#/components/schemas/ProblemDetails'
Michel Roy's avatar
Michel Roy committed
      description: 'Not Found :  used when a client provided a URI that cannot be mapped to a valid resource URI.'
      content:
Michel Roy's avatar
Michel Roy committed
        application/problem+json:
Michel Roy's avatar
Michel Roy committed
          schema:
Michel Roy's avatar
Michel Roy committed
            $ref: '#/components/schemas/ProblemDetails'
Michel Roy's avatar
Michel Roy committed
      description: 'Precondition failed :  used when a condition has failed during conditional requests, e.g. when
        using ETags to avoid write conflicts when using PUT'
      content:
Michel Roy's avatar
Michel Roy committed
        application/problem+json:
Michel Roy's avatar
Michel Roy committed
          schema:
Michel Roy's avatar
Michel Roy committed
            $ref: '#/components/schemas/ProblemDetails'
  parameters:
Michel Roy's avatar
Michel Roy committed
    Path.allocationId:
      name: allocationId
Michel Roy's avatar
Michel Roy committed
      in: "path"
      description: "Represents a bandwidth allocation instance"
      required: true
      schema:
        type: string
Michel Roy's avatar
Michel Roy committed
    Query.app_instance_id:
      name: app_instance_id
Michel Roy's avatar
Michel Roy committed
      in: "query"
      description: "A MEC application instance may use multiple app_instance_ids as an input parameter to query the bandwidth allocation of a list of MEC application instances. app_instance_id corresponds to appInsId defined in table 7.2.2-1. See note."
      required: false
      schema:
        type: array
        items:
          type: string
Michel Roy's avatar
Michel Roy committed
    Query.app_name:
      name: app_name
Michel Roy's avatar
Michel Roy committed
      in: "query"
      description: "A MEC application instance may use multiple app_names as an input parameter to query the bandwidth allocation of a list of MEC application instances. app_name corresponds to appName defined in table 7.2.2-1. See note."
      required: false
      schema:
        type: array
        items:
          type: string
Michel Roy's avatar
Michel Roy committed
    Query.session_id:
      name: session_id
Michel Roy's avatar
Michel Roy committed
      in: "query"
      description: "A MEC application instance may use session_id as an input parameter to query the bandwidth allocation of a list of sessions. session_id corresponds to allocationId defined in table 7.2.2-1. See note."
      required: false
      schema:
        type: array
        items:
          type: string
  schemas:
    BwInfo:
      title: BwInfo
        allocationId:
          description: Bandwidth allocation instance identifier
          type: string
          x-etsi-mec-cardinality: 0..1
          x-etsi-mec-origin-type: String
        appName:
          description: Name of the application 
          type: string
          x-etsi-mec-cardinality: 0..1
          x-etsi-mec-origin-type: String
Michel Roy's avatar
Michel Roy committed
        allocationDirection:
          description: 'The direction of the requested BW allocation:
            00 = Downlink (towards the UE)
            01 = Uplink (towards the application/session)
            10 = Symmetrical'
          type: string
          x-etsi-mec-cardinality: '1'
          x-etsi-mec-origin-type: String
        appInsId:
Michel Roy's avatar
Michel Roy committed
          description: Application instance identifier
          type: string
          x-etsi-mec-cardinality: '1'
          x-etsi-mec-origin-type: String
        fixedAllocation:
          description: Size of requested fixed BW allocation in [bps]
          type: string
          x-etsi-mec-cardinality: '1'
          x-etsi-mec-origin-type: String
        fixedBWPriority:
          description: Indicates the allocation priority when dealing with several applications or sessions in parallel. Values are not defined in the present document
          enum:
          - SEE_DESCRIPTION
          type: string
          x-etsi-mec-cardinality: 0..1
          x-etsi-mec-origin-type: Enum
        requestType:
Michel Roy's avatar
Michel Roy committed
          description: 'Numeric value (0 - 255) corresponding to specific type of consumer as following:
            0 = APPLICATION_SPECIFIC_BW_ALLOCATION
            1 = SESSION_SPECIFIC_BW_ALLOCATION'
Michel Roy's avatar
Michel Roy committed
          type: integer
Michel Roy's avatar
Michel Roy committed
          enum:
          - 0
          - 1
          x-etsi-mec-cardinality: '1'
          x-etsi-mec-origin-type: Enum_inlined
        sessionFilter:
          title: sessionFilter
Michel Roy's avatar
Michel Roy committed
          description: Session filtering criteria, applicable when requestType is set as SESSION_SPECIFIC_BW_ALLOCATION. Any filtering criteria shall define a single session only. In case multiple sessions match sessionFilter the request shall be rejected
          items:
            type: object
            properties:
              dstAddress:
                description: Destination address identity of session. The string for an  IPv4 address shall
                  be formatted in the "dotted decimal" notation as defined in IETF RFC 1166 [10]. The string
                  for an IPv6 address shall be formatted according to clause 4 of IETF RFC 5952 [11], with in
                  CIDR notation [12] used to provide the routing prefix 
Michel Roy's avatar
Michel Roy committed
                type: string
                x-etsi-mec-cardinality: 0..1
                x-etsi-mec-origin-type: String
              dstPort:
                description: Destination port identity of session
                items:
                  type: string
                minItems: 0
                type: array
                x-etsi-mec-cardinality: 0..N
                x-etsi-mec-origin-type: String
              protocol:
                description: Protocol number
                type: string
                x-etsi-mec-cardinality: 0..1
                x-etsi-mec-origin-type: String
              sourceIp:
                description: Source address identity of session. The string for an IPv4 address shall be
                  formatted in the "dotted decimal" notation as defined in IETF RFC 1166 [10]. The string for 
                  an IPv6 address shall be formatted according to clause 4 of IETF RFC 5952 [11], with in CIDR
                  notation [12] used to provide the routing prefix
Michel Roy's avatar
Michel Roy committed
                type: string
                x-etsi-mec-cardinality: 0..1
                x-etsi-mec-origin-type: String
              sourcePort:
                description: Source port identity of session
                items:
                  type: string
                minItems: 0
                type: array
                x-etsi-mec-cardinality: 0..N
                x-etsi-mec-origin-type: String
          minItems: 0
          type: array
          x-etsi-mec-cardinality: 0..N
          x-etsi-mec-origin-type: Structure (inlined)
        timeStamp:
          title: timeStamp
Michel Roy's avatar
Michel Roy committed
          description: Time stamp to indicate when the corresponding information elements are sent
          properties:
            nanoSeconds:
              description: The nanoseconds part of the Time. Time is defined as Unix-time since January 1, 1970, 00:00:00 UTC
Michel Roy's avatar
Michel Roy committed
              format: uint32
              type: integer
Michel Roy's avatar
Michel Roy committed
              x-etsi-mec-cardinality: '1'
              x-etsi-mec-origin-type: Uint32
            seconds:
Michel Roy's avatar
Michel Roy committed
              format: uint32
Michel Roy's avatar
Michel Roy committed
              type: integer
              description: The seconds part of the Time. Time is defined as Unixtime since January 1, 1970, 00:00:00 UTC
              x-etsi-mec-cardinality: '1'
              x-etsi-mec-origin-type: Uint32
          required:
          - seconds
          - nanoSeconds
          type: object
          x-etsi-mec-cardinality: 0..1
          x-etsi-mec-origin-type: Structure (inlined)
      required:
      - appInsId
      - requestType
      - fixedAllocation
      - allocationDirection
      type: object
Michel Roy's avatar
Michel Roy committed
      x-etsi-ref: 7.2.2
    BwInfoDeltas:
      title: BwInfoDeltas
      properties:
        allocationId:
          description: Bandwidth allocation instance identifier
          type: string
          x-etsi-mec-cardinality: '1'
          x-etsi-mec-origin-type: String
Michel Roy's avatar
Michel Roy committed
        allocationDirection:
          description: 'The direction of the requested BW allocation:
            00 = Downlink (towards the UE)
            01 = Uplink (towards the application/session)
            10 = Symmetrical'
          type: string
          x-etsi-mec-cardinality: 0..1
          x-etsi-mec-origin-type: String
        appInsId:
Michel Roy's avatar
Michel Roy committed
          description: Application instance identifier
          type: string
          x-etsi-mec-cardinality: '1'
          x-etsi-mec-origin-type: String
        fixedAllocation:
          description: Size of requested fixed BW allocation in [bps]
          type: string
          x-etsi-mec-cardinality: 0..1
          x-etsi-mec-origin-type: String
        fixedBWPriority:
          description: Indicates the allocation priority when dealing with several applications or sessions in parallel. Values are not defined in the present document
          enum:
          - SEE DESCRIPTION
          type: string
          x-etsi-mec-cardinality: 0..1
          x-etsi-mec-origin-type: Enum_inlined
        requestType:
Michel Roy's avatar
Michel Roy committed
          description: 'Numeric value (0 - 255) corresponding to specific type of consumer as following:
            0 = APPLICATION_SPECIFIC_BW_ALLOCATION
            1 = SESSION_SPECIFIC_BW_ALLOCATION'
          type: integer
Michel Roy's avatar
Michel Roy committed
          enum:
          - 0
          - 1
          x-etsi-mec-cardinality: '1'
          x-etsi-mec-origin-type: Enum_inlined
        sessionFilter:
          title: sessionFilter
Michel Roy's avatar
Michel Roy committed
          description: Session filtering criteria, applicable when requestType is set as SESSION_SPECIFIC_BW_ALLOCATION. Any filtering criteria shall define a single session only. In case multiple sessions match sessionFilter the request shall be rejected
          items:
            type: object
            properties:
              dstAddress:
                description: Destination address identity of session. The string for an IPv4 address shall
                  be formatted in the "dotted decimal" notation as defined in IETF RFC 1166 [10]. The string
                  for an IPv6 address shall be formatted according to clause 4 of IETF RFC 5952 [11], with
                  in CIDR notation [12] used to provide the routing prefix
Michel Roy's avatar
Michel Roy committed
                type: string
                x-etsi-mec-cardinality: 0..1
                x-etsi-mec-origin-type: String
              dstPort:
                description: Destination port identity of session
                items:
                  type: string
                minItems: 0
                type: array
                x-etsi-mec-cardinality: 0..N
                x-etsi-mec-origin-type: String
              protocol:
                description: Protocol number
                type: string
                x-etsi-mec-cardinality: 0..1
                x-etsi-mec-origin-type: String
              sourceIp:
                description: Source address identity of session. The string for an IPv4 address shall be
                  formatted in the "dotted decimal" notation as defined in IETF RFC 1166 [10]. The string
                  for an IPv6 address shall be formatted according to clause 4 of IETF RFC 5952 [11], with
                  in CIDR notation [12] used to provide the routing prefix
Michel Roy's avatar
Michel Roy committed
                type: string
                x-etsi-mec-cardinality: 0..1
                x-etsi-mec-origin-type: String
              sourcePort:
                description: 'Source port identity of session '
                items:
                  type: string
                minItems: 0
                type: array
                x-etsi-mec-cardinality: 0..N
                x-etsi-mec-origin-type: String
          minItems: 0
          type: array
          x-etsi-mec-cardinality: 0..N
          x-etsi-mec-origin-type: Structure (inlined)
      required:
      - allocationId
Michel Roy's avatar
Michel Roy committed
      - appInsId
      - requestType
      type: object
      x-etsi-ref: 7.2.3
    ProblemDetails:
      title: ProblemDetails
      properties:
Michel Roy's avatar
Michel Roy committed
        detail:
          description: A human-readable explanation specific to this occurrence of the problem
          type: string
          x-etsi-mec-cardinality: 0..1
          x-etsi-mec-origin-type: String
        instance:
          description: A URI reference that identifies the specific occurrence of the problem
          format: uri
          type: string
          x-etsi-mec-cardinality: 0..1
          x-etsi-mec-origin-type: URI
        status:
          description: The HTTP status code for this occurrence of the problem
Michel Roy's avatar
Michel Roy committed
          format: uint32
Michel Roy's avatar
Michel Roy committed
          type: integer
          x-etsi-mec-cardinality: 0..1
          x-etsi-mec-origin-type: Uint32
        title:
          description: A short, human-readable summary of the problem type
          type: string
          x-etsi-mec-cardinality: 0..1
          x-etsi-mec-origin-type: String
        type:
          description: A URI reference according to IETF RFC 3986 that identifies the problem type
          format: uri
          type: string
          x-etsi-mec-cardinality: 0..1
          x-etsi-mec-origin-type: URI
      type: object