BwManagementApi.yaml 17.3 KB
Newer Older
Michel Roy's avatar
Michel Roy committed
1
openapi: 3.0.0
2
info:
Michel Roy's avatar
Michel Roy committed
3 4
  contact:
    url: https://forge.etsi.org/rep/mec/gs015-bandwith-mgmt-api
Michel Roy's avatar
Michel Roy committed
5 6 7
  title: 'ETSI GS MEC 015 Bandwidth Management API'
  version: 2.1.1
  description: The ETSI MEC ISG Bandwidth Management API described using OpenAPI.
8
  license:
ETSI CTI's avatar
ETSI CTI committed
9
    name: BSD-3-Clause
Michel Roy's avatar
Michel Roy committed
10 11
    url: 'https://forge.etsi.org/legal-matters'

12
externalDocs:
Michel Roy's avatar
Michel Roy committed
13 14 15
  description: ETSI GS MEC015 V2.1.1 Traffic Management APIs
  url: 'https://www.etsi.org/deliver/etsi_gs/MEC/001_099/015/02.01.01_60/gs_MEC015v020101p.pdf'

16
servers:
Michel Roy's avatar
Michel Roy committed
17 18 19 20
  - url: 'https://localhost/bwm/v1'

tags:
- name: "bwm"
Michel Roy's avatar
Michel Roy committed
21

22
paths:
Michel Roy's avatar
Michel Roy committed
23
  /bw_allocations:
24
    get:
25
      tags:
Michel Roy's avatar
Michel Roy committed
26
      - "bwm"
Michel Roy's avatar
Michel Roy committed
27 28 29 30 31 32 33
      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'
34
      responses:
Michel Roy's avatar
Michel Roy committed
35 36 37 38 39
        200:
          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
40 41 42
                type: array
                items:
                  $ref: "#/components/schemas/BwInfo"
Michel Roy's avatar
Michel Roy committed
43 44 45 46 47 48
        400:
          $ref: "#/components/responses/400"
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
49
    post:
50
      tags:
Michel Roy's avatar
Michel Roy committed
51
      - "bwm"
Michel Roy's avatar
Michel Roy committed
52 53 54 55 56 57 58 59 60 61
      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
62
              $ref: '#/components/schemas/BwInfo'
63
      responses:
Michel Roy's avatar
Michel Roy committed
64 65 66 67 68
        201:
          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
69
                $ref: "#/components/schemas/BwInfo"
Michel Roy's avatar
Michel Roy committed
70 71 72 73 74 75 76
        400:
          $ref: "#/components/responses/400"
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
  /bw_allocations/{allocationId}:
77
    get:
78
      tags:
Michel Roy's avatar
Michel Roy committed
79
      - "bwm"
Michel Roy's avatar
Michel Roy committed
80 81 82 83 84
      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'
85
      responses:
Michel Roy's avatar
Michel Roy committed
86 87 88 89 90
        200:
          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
91
                $ref: "#/components/schemas/BwInfo"
Michel Roy's avatar
Michel Roy committed
92 93 94 95 96 97
        400:
          $ref: "#/components/responses/400"
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
98
    put:
99
      tags:
Michel Roy's avatar
Michel Roy committed
100
      - "bwm"
Michel Roy's avatar
Michel Roy committed
101 102 103 104 105 106 107 108 109
      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
110
              $ref: '#/components/schemas/BwInfo'
Michel Roy's avatar
Michel Roy committed
111 112
      parameters:
        - $ref: '#/components/parameters/Path.allocationId'
113
      responses:
Michel Roy's avatar
Michel Roy committed
114 115 116 117 118
        200:
          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
119
                $ref: "#/components/schemas/BwInfo"
Michel Roy's avatar
Michel Roy committed
120 121 122 123 124 125 126 127
        400:
          $ref: "#/components/responses/400"
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
        412:
          $ref: '#/components/responses/412'
128
    patch:
129
      tags:
Michel Roy's avatar
Michel Roy committed
130
      - "bwm"
Michel Roy's avatar
Michel Roy committed
131 132 133 134 135 136 137 138 139
      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
140
              $ref: '#/components/schemas/BwInfoDeltas'
Michel Roy's avatar
Michel Roy committed
141 142
      parameters:
        - $ref: '#/components/parameters/Path.allocationId'
143
      responses:
Michel Roy's avatar
Michel Roy committed
144 145 146 147 148
        200:
          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
149
                $ref: "#/components/schemas/BwInfo"
Michel Roy's avatar
Michel Roy committed
150 151 152 153 154 155 156 157
        400:
          $ref: "#/components/responses/400"
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
        412:
          $ref: '#/components/responses/412'
158
    delete:
159
      tags:
Michel Roy's avatar
Michel Roy committed
160
      - "bwm"
Michel Roy's avatar
Michel Roy committed
161 162 163 164 165
      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'
166
      responses:
Michel Roy's avatar
Michel Roy committed
167 168 169 170 171 172
        204:
          $ref: '#/components/responses/204'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
173
components:
Michel Roy's avatar
Michel Roy committed
174 175 176 177 178 179
  responses:
    204:
      description: "Upon success, a response 204 No Content without any response body is returned."
    400:
      description: 'Bad Request : used to indicate that incorrect parameters were passed to the request.'
      content:
Michel Roy's avatar
Michel Roy committed
180
        application/problem+json:
Michel Roy's avatar
Michel Roy committed
181
          schema:
Michel Roy's avatar
Michel Roy committed
182
            $ref: '#/components/schemas/ProblemDetails'
Michel Roy's avatar
Michel Roy committed
183 184 185
    403:
      description: 'Forbidden :  operation is not allowed given the current status of the resource.'
      content:
Michel Roy's avatar
Michel Roy committed
186
        application/problem+json:
Michel Roy's avatar
Michel Roy committed
187
          schema:
Michel Roy's avatar
Michel Roy committed
188
            $ref: '#/components/schemas/ProblemDetails'
Michel Roy's avatar
Michel Roy committed
189 190 191
    404:
      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
192
        application/problem+json:
Michel Roy's avatar
Michel Roy committed
193
          schema:
Michel Roy's avatar
Michel Roy committed
194
            $ref: '#/components/schemas/ProblemDetails'
Michel Roy's avatar
Michel Roy committed
195 196 197 198
    412:
      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
199
        application/problem+json:
Michel Roy's avatar
Michel Roy committed
200
          schema:
Michel Roy's avatar
Michel Roy committed
201
            $ref: '#/components/schemas/ProblemDetails'
202
  parameters:
Michel Roy's avatar
Michel Roy committed
203
    Path.allocationId:
204
      name: allocationId
Michel Roy's avatar
Michel Roy committed
205 206
      in: "path"
      description: "Represents a bandwidth allocation instance"
207 208 209
      required: true
      schema:
        type: string
Michel Roy's avatar
Michel Roy committed
210
    Query.app_instance_id:
211
      name: app_instance_id
Michel Roy's avatar
Michel Roy committed
212 213
      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. See note."
214 215 216 217 218
      required: false
      schema:
        type: array
        items:
          type: string
Michel Roy's avatar
Michel Roy committed
219
    Query.app_name:
220
      name: app_name
Michel Roy's avatar
Michel Roy committed
221 222
      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. See note."
223 224 225 226 227
      required: false
      schema:
        type: array
        items:
          type: string
Michel Roy's avatar
Michel Roy committed
228
    Query.session_id:
229
      name: session_id
Michel Roy's avatar
Michel Roy committed
230 231
      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. See note."
232 233 234 235 236 237 238
      required: false
      schema:
        type: array
        items:
          type: string
  schemas:
    BwInfo:
239
      properties:
Michel Roy's avatar
Michel Roy committed
240 241 242 243 244 245 246 247
        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
248
        appInsId:
Michel Roy's avatar
Michel Roy committed
249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264
          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
265
        requestType:
Michel Roy's avatar
Michel Roy committed
266 267 268
          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
269
          type: integer
Michel Roy's avatar
Michel Roy committed
270 271 272 273 274
          enum:
          - 0
          - 1
          x-etsi-mec-cardinality: '1'
          x-etsi-mec-origin-type: Enum_inlined
275
        sessionFilter:
Michel Roy's avatar
Michel Roy committed
276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319
          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 (including range)
                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 (including range)
                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:
          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
320 321
              format: uint32
              type: integer
Michel Roy's avatar
Michel Roy committed
322 323 324
              x-etsi-mec-cardinality: '1'
              x-etsi-mec-origin-type: Uint32
            seconds:
Michel Roy's avatar
Michel Roy committed
325
              format: uint32
Michel Roy's avatar
Michel Roy committed
326 327 328 329 330 331 332 333 334 335 336 337 338 339 340
              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
341
      type: object
Michel Roy's avatar
Michel Roy committed
342 343
      x-etsi-ref: 7.2.2
    BwInfoDeltas:
344
      properties:
Michel Roy's avatar
Michel Roy committed
345 346 347 348 349 350 351 352
        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
353
        appInsId:
Michel Roy's avatar
Michel Roy committed
354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369
          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
370
        requestType:
Michel Roy's avatar
Michel Roy committed
371 372 373 374 375 376 377 378 379
          description: 'Numeric value (0 - 255) corresponding to specific type of consumer as following:
            0 = APPLICATION_SPECIFIC_BW_ALLOCATION
            1 = SESSION_SPECIFIC_BW_ALLOCATION'
          type: string
          enum:
          - 0
          - 1
          x-etsi-mec-cardinality: '1'
          x-etsi-mec-origin-type: Enum_inlined
380
        sessionFilter:
Michel Roy's avatar
Michel Roy committed
381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419
          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 (including range)
                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 (including range)
                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)
420
      required:
Michel Roy's avatar
Michel Roy committed
421 422 423 424 425
      - appInsId
      - requestType
      type: object
      x-etsi-ref: 7.2.3
    ProblemDetails:
426
      properties:
Michel Roy's avatar
Michel Roy committed
427 428 429 430 431 432 433 434 435 436 437 438 439
        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
440
          format: uint32
Michel Roy's avatar
Michel Roy committed
441 442 443 444 445 446 447 448 449 450 451 452 453 454 455
          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