cps-ncmp-rest/docs/openapi/components.yaml

   1 #  ============LICENSE_START=======================================================
   2 #  Copyright (C) 2021-2023 Nordix Foundation
   3 #  Modifications Copyright (C) 2021 Pantheon.tech
   4 #  Modifications Copyright (C) 2022 Bell Canada
   5 #  ================================================================================
   6 #  Licensed under the Apache License, Version 2.0 (the "License");
   7 #  you may not use this file except in compliance with the License.
   8 #  You may obtain a copy of the License at
   9 #
  10 #        http://www.apache.org/licenses/LICENSE-2.0
  11 #
  12 #  Unless required by applicable law or agreed to in writing, software
  13 #  distributed under the License is distributed on an "AS IS" BASIS,
  14 #  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15 #  See the License for the specific language governing permissions and
  16 #  limitations under the License.
  17 #
  18 #  SPDX-License-Identifier: Apache-2.0
  19 #  ============LICENSE_END=========================================================
  20
  21 components:
  22   schemas:
  23     # Common Schemas
  24     ErrorMessage:
  25       type: object
  26       title: Error
  27       properties:
  28         status:
  29           type: string
  30         message:
  31           type: string
  32         details:
  33           type: string
  34     # DMI Server Exception Schema
  35     DmiErrorMessage:
  36       title: DMI Error Message
  37       type: object
  38       properties:
  39         message:
  40           type: string
  41           example: 'Bad Gateway Error Message NCMP'
  42         dmi-response:
  43           type: object
  44           properties:
  45             http-code:
  46               type: integer
  47               example: 400
  48             body:
  49               type: string
  50               example: Bad Request
  51     # Request Schemas
  52     RestDmiPluginRegistration:
  53       type: object
  54       properties:
  55         dmiPlugin:
  56           type: string
  57           example: my-dmi-plugin
  58           default: ""
  59         dmiDataPlugin:
  60           type: string
  61           example: my-dmi-data-plugin
  62           default: ""
  63         dmiModelPlugin:
  64           type: string
  65           example: my-dmi-model-plugin
  66           default: ""
  67         createdCmHandles:
  68           type: array
  69           items:
  70             $ref: '#/components/schemas/RestInputCmHandle'
  71         updatedCmHandles:
  72           type: array
  73           items:
  74             $ref: '#/components/schemas/RestInputCmHandle'
  75             example:
  76               cmHandle: my-cm-handle
  77               cmHandleProperties:
  78                 add-my-property: add-property
  79                 update-my-property: updated-property
  80                 delete-my-property: '~'
  81               publicCmHandleProperties:
  82                 add-my-property: add-property
  83                 update-my-property: updated-property
  84                 delete-my-property: '~'
  85         removedCmHandles:
  86           type: array
  87           items:
  88             type: string
  89           example: [ my-cm-handle1, my-cm-handle2, my-cm-handle3 ]
  90         upgradedCmHandles:
  91           $ref: '#/components/schemas/UpgradedCmHandles'
  92     DmiPluginRegistrationErrorResponse:
  93       type: object
  94       properties:
  95         failedCreatedCmHandles:
  96           type: array
  97           items:
  98             $ref: '#/components/schemas/CmHandlerRegistrationErrorResponse'
  99         failedUpdatedCmHandles:
 100           type: array
 101           items:
 102             $ref: '#/components/schemas/CmHandlerRegistrationErrorResponse'
 103         failedRemovedCmHandles:
 104           type: array
 105           items:
 106             $ref: '#/components/schemas/CmHandlerRegistrationErrorResponse'
 107         failedUpgradeCmHandles:
 108           type: array
 109           items:
 110             $ref: '#/components/schemas/CmHandlerRegistrationErrorResponse'
 111     CmHandlerRegistrationErrorResponse:
 112       type: object
 113       properties:
 114         cmHandle:
 115           type: string
 116           example: my-cm-handle
 117         errorCode:
 118           type: string
 119           example: '00'
 120         errorText:
 121           type: string
 122           example: 'Unknown error. <error-details>'
 123
 124     RestInputCmHandle:
 125       required:
 126         - cmHandle
 127       type: object
 128       properties:
 129         cmHandle:
 130           type: string
 131           example: my-cm-handle
 132         cmHandleProperties:
 133           $ref: '#/components/schemas/RestCmHandleProperties'
 134         publicCmHandleProperties:
 135           $ref: '#/components/schemas/RestCmHandleProperties'
 136         moduleSetTag:
 137           type: string
 138           example: "my-module-set-tag"
 139     RestCmHandleProperties:
 140       type: object
 141       additionalProperties:
 142         type: string
 143         example: my-property
 144     #Module upgrade schema
 145     UpgradedCmHandles:
 146       required:
 147         - cmHandles
 148       type: object
 149       properties:
 150         cmHandles:
 151           type: array
 152           items:
 153             type: string
 154           example: [ my-cm-handle1, my-cm-handle2, my-cm-handle3 ]
 155         moduleSetTag:
 156           type: string
 157           example: 'my-module-set-tag'
 158
 159     #Response Schemas
 160     RestModuleReference:
 161       type: object
 162       title: Module reference details
 163       properties:
 164         moduleName:
 165           type: string
 166           example: my-module-name
 167         revision:
 168           type: string
 169           example: my-module-revision
 170
 171     RestModuleDefinition:
 172       type: object
 173       title: Module definitions
 174       properties:
 175         moduleName:
 176           type: string
 177           example: my-module-name
 178         revision:
 179           type: string
 180           example: 2020-09-15
 181         content:
 182           type: string
 183           example: |
 184             module stores {
 185               yang-version 1.1;
 186               namespace 'org:onap:ccsdk:sample';
 187               prefix book-store;
 188               revision '2020-09-15' {
 189                 description
 190                 'Sample Model';
 191               }
 192             }
 193
 194     CmHandleQueryParameters:
 195       type: object
 196       title: Cm Handle query parameters for executing cm handle search
 197       properties:
 198         cmHandleQueryParameters:
 199           type: array
 200           items:
 201             $ref: '#/components/schemas/ConditionProperties'
 202         conditions:
 203           deprecated: true
 204           type: array
 205           items:
 206             $ref: '#/components/schemas/OldConditionProperties'
 207           description: not necessary, it is just for backward compatibility
 208
 209     ConditionProperties:
 210       properties:
 211         conditionName:
 212           type: string
 213         conditionParameters:
 214           type: array
 215           items:
 216             type: object
 217             additionalProperties:
 218               type: string
 219     OldConditionProperties:
 220       deprecated: true
 221       properties:
 222         name:
 223           type: string
 224         conditionParameters:
 225           type: array
 226           items:
 227             $ref: '#/components/schemas/ModuleNameAsJsonObject'
 228     ModuleNameAsJsonObject:
 229       properties:
 230         moduleName:
 231           type: string
 232           example: my-module
 233
 234     RestOutputCmHandle:
 235       type: object
 236       title: CM handle Details
 237       properties:
 238         cmHandle:
 239           type: string
 240           example: my-cm-handle1
 241         publicCmHandleProperties:
 242           $ref: '#/components/schemas/CmHandlePublicProperties'
 243         state:
 244           $ref: '#/components/schemas/CmHandleCompositeState'
 245         trustLevel:
 246           $ref: '#/components/schemas/CmHandleTrustLevel'
 247     CmHandlePublicProperties:
 248       type: object
 249       items:
 250         type: object
 251         additionalProperties:
 252           type: string
 253           example: 'Book Type'
 254     CmHandleCompositeState:
 255       type: object
 256       properties:
 257         cmHandleState:
 258           type: string
 259           example: ADVISED
 260         lockReason:
 261           $ref: '#/components/schemas/lock-reason'
 262         lastUpdateTime:
 263           type: string
 264           example: 2022-12-31T20:30:40.000+0000
 265         dataSyncEnabled:
 266           type: boolean
 267           example: false
 268         dataSyncState:
 269           $ref: '#/components/schemas/dataStores'
 270     CmHandleTrustLevel:
 271       type: string
 272       description: Current trust level of the relevant CM handle ID.
 273       example: COMPLETE
 274
 275     lock-reason:
 276       type: object
 277       properties:
 278         reason:
 279           type: string
 280           example: LOCKED_MISBEHAVING
 281         details:
 282           type: string
 283           example: locked due to failure in module sync
 284
 285     dataStores:
 286       type: object
 287       properties:
 288         operational:
 289           $ref: '#/components/schemas/sync-state'
 290         running:
 291           $ref: '#/components/schemas/sync-state'
 292
 293     sync-state:
 294       type: object
 295       properties:
 296         syncState:
 297           type: string
 298           example: NONE_REQUESTED
 299         lastSyncTime:
 300           type: string
 301           example: 2022-12-31T20:30:40.000+0000
 302
 303     RestOutputCmHandlePublicProperties:
 304       type: object
 305       properties:
 306         publicCmHandleProperties:
 307           $ref: '#/components/schemas/CmHandlePublicProperties'
 308
 309     RestOutputCmHandleCompositeState:
 310       type: object
 311       properties:
 312         state:
 313           $ref: '#/components/schemas/CmHandleCompositeState'
 314     # Data Operation Request Schemas
 315     DataOperationRequest:
 316       type: object
 317       title: execute data operation for given array of operations
 318       properties:
 319         operations:
 320           type: array
 321           items:
 322             $ref: '#/components/schemas/DataOperationDefinition'
 323           description: contains group of data operation requests
 324     DataOperationDefinition:
 325       required:
 326         - operation
 327         - datastore
 328         - operationId
 329       properties:
 330         operation:
 331           type: string
 332           example: 'read'
 333         operationId:
 334           type: string
 335           example: '12'
 336         datastore:
 337           type: string
 338           example: 'ncmp-datastore:passthrough-operational'
 339         options:
 340           type: string
 341           example: '(fields=schemas/schema)'
 342         resourceIdentifier:
 343           type: string
 344           example: 'parent/child'
 345         targetIds:
 346           type: array
 347           items:
 348             type: string
 349             example: [ "da310eecdb8d44c2acc0ddaae01174b1","c748c58f8e0b438f9fd1f28370b17d47" ]
 350
 351   examples:
 352     dataSampleRequest:
 353       summary: Sample request
 354       description: Sample request body
 355       value:
 356         test:bookstore:
 357           bookstore-name: Chapters
 358           categories:
 359             - code: '01'
 360               name: SciFi
 361               books:
 362                 - authors:
 363                     - Iain M. Banks
 364                     - Ursula K. Le Guin
 365             - code: '02'
 366               name: kids
 367               books:
 368                 - authors:
 369                     - Philip Pullman
 370
 371     dataSamplePatchRequest:
 372       summary: Sample patch request
 373       description: Sample patch request body
 374       value:
 375         ietf-restconf:yang-patch:
 376           patch-id: patch-1
 377           edit:
 378             - edit-id: edit1
 379               operation: merge
 380               target: /
 381               value:
 382                 test:bookstore:
 383                   bookstore-name: Chapters
 384                   categories:
 385                     - code: '01'
 386                       name: Science
 387                       books:
 388                         - authors:
 389                             - Author1
 390                             - Author2
 391                     - code: '02'
 392                       name: Arts
 393                       books:
 394                         - authors:
 395                             - Author3
 396             - edit-id: edit2
 397               operation: merge
 398               target: /
 399               value:
 400                 test:bookstore:
 401                   bookstore-name: Novels
 402                   categories:
 403                     - code: '03'
 404                       name: History
 405                       books:
 406                         - authors:
 407                             - Iain M. Banks
 408                             - Ursula K. Le Guin
 409                     - code: '04'
 410                       name: Fiction
 411                       books:
 412                         - authors:
 413                             - Philip Pullman
 414
 415     dataSampleResponse:
 416       summary: Sample response
 417       description: Sample response for selecting 'sample 1'.
 418       value:
 419         bookstore:
 420           categories:
 421             - code: '01'
 422               books:
 423                 - authors:
 424                     - Iain M. Banks
 425                     - Ursula K. Le Guin
 426               name: SciFi
 427             - code: '02'
 428               books:
 429                 - authors:
 430                     - Philip Pullman
 431               name: kids
 432
 433     allCmHandleQueryParameters:
 434       value:
 435         cmHandleQueryParameters:
 436           - conditionName: hasAllModules
 437             conditionParameters:
 438               - { "moduleName": "my-module-1" }
 439               - { "moduleName": "my-module-2" }
 440               - { "moduleName": "my-module-3" }
 441           - conditionName: hasAllProperties
 442             conditionParameters:
 443               - { "Color": "yellow" }
 444               - { "Shape": "circle" }
 445               - { "Size": "small" }
 446           - conditionName: cmHandleWithCpsPath
 447             conditionParameters:
 448               - { "cpsPath": "//state[@cm-handle-state='ADVISED']" }
 449     pubPropCmHandleQueryParameters:
 450       value:
 451         cmHandleQueryParameters:
 452           - conditionName: hasAllProperties
 453             conditionParameters:
 454               - { "Color": "yellow" }
 455               - { "Shape": "circle" }
 456               - { "Size": "small" }
 457     modulesCmHandleQueryParameters:
 458       value:
 459         cmHandleQueryParameters:
 460           - conditionName: hasAllModules
 461             conditionParameters:
 462               - { "moduleName": "my-module-1" }
 463               - { "moduleName": "my-module-2" }
 464               - { "moduleName": "my-module-3" }
 465     cpsPathCmHandleStateQueryParameters:
 466       value:
 467         cmHandleQueryParameters:
 468           - conditionName: cmHandleWithCpsPath
 469             conditionParameters:
 470               - { "cpsPath": "//state[@cm-handle-state='LOCKED']" }
 471     cpsPathCmHandleDataSyncQueryParameters:
 472       value:
 473         cmHandleQueryParameters:
 474           - conditionName: cmHandleWithCpsPath
 475             conditionParameters:
 476               - { "cpsPath": "//state[@data-sync-enabled='true']" }
 477
 478   parameters:
 479     cmHandleInPath:
 480       name: cm-handle
 481       in: path
 482       description: The identifier for a network function, network element, subnetwork or any other cm object by managed Network CM Proxy
 483       required: true
 484       schema:
 485         type: string
 486         example: my-cm-handle
 487     dataSyncEnabled:
 488       name: dataSyncEnabled
 489       in: query
 490       description: Is used to enable or disable the data synchronization flag
 491       required: true
 492       schema:
 493         type: boolean
 494         example: true
 495     xpathInQuery:
 496       name: xpath
 497       in: query
 498       description: xpath
 499       required: false
 500       schema:
 501         type: string
 502         default: /
 503     requiredXpathInQuery:
 504       name: xpath
 505       in: query
 506       description: xpath
 507       required: true
 508       schema:
 509         type: string
 510     includeDescendantsOptionInQuery:
 511       name: include-descendants
 512       in: query
 513       description: Determines if descendants are included in response
 514       required: false
 515       schema:
 516         type: boolean
 517         default: false
 518     cpsPathInQuery:
 519       name: cps-path
 520       in: query
 521       description: For more details on cps path, please refer https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html
 522       required: false
 523       schema:
 524         type: string
 525         default: /
 526       examples:
 527         container cps path:
 528           value: //bookstore
 529         list attributes cps path:
 530           value: //categories[@code=1]
 531     dmiPluginIdentifierInQuery:
 532       name: dmi-plugin-identifier
 533       in: query
 534       description: dmi-plugin-identifier
 535       required: true
 536       schema:
 537         type: string
 538         example: my-dmi-plugin
 539     resourceIdentifierInQuery:
 540       name: resourceIdentifier
 541       in: query
 542       description: The format of resource identifier depend on the associated DMI Plugin implementation. For ONAP DMI Plugin it will be RESTConf paths but it can really be anything.
 543       required: true
 544       allowReserved: true
 545       schema:
 546         type: string
 547       examples:
 548         sample 1:
 549           value:
 550             resourceIdentifier: \shops\bookstore
 551         sample 2:
 552           value:
 553             resourceIdentifier: \shops\bookstore\categories[@code=1]
 554         sample 3:
 555           value:
 556             resourceIdentifier: parent=shops,child=bookstore
 557     optionsParamInQuery:
 558       name: options
 559       in: query
 560       description: options parameter in query, it is mandatory to wrap key(s)=value(s) in parenthesis'()'. The format of options parameter depend on the associated DMI Plugin implementation.
 561       required: false
 562       schema:
 563         type: string
 564       allowReserved: true
 565       examples:
 566         sample 1:
 567           value:
 568             options: (depth=3)
 569         sample 2:
 570           value:
 571             options: (fields=book)
 572         sample 3:
 573           value:
 574             options: (depth=2,fields=book/authors)
 575     topicParamInQuery:
 576       name: topic
 577       in: query
 578       description: topic parameter in query.
 579       required: false
 580       schema:
 581         type: string
 582       allowReserved: true
 583       examples:
 584         sample 1:
 585           value:
 586             topic: my-topic-name
 587     requiredTopicParamInQuery:
 588       name: topic
 589       in: query
 590       description: mandatory topic parameter in query.
 591       required: true
 592       schema:
 593         type: string
 594       allowReserved: true
 595       examples:
 596         sample 1:
 597           value:
 598             topic: my-topic-name
 599     contentParamInHeader:
 600       name: Content-Type
 601       in: header
 602       required: false
 603       description: Content parameter for request, if content parameter is null, default value is application/json.
 604       schema:
 605         type: string
 606         default: application/json
 607         example: application/yang-data+json
 608     datastoreName:
 609       name: datastore-name
 610       in: path
 611       description: The type of the requested data
 612       required: true
 613       schema:
 614         type: string
 615         example: ncmp-datastore:running
 616
 617   responses:
 618     NotFound:
 619       description: The specified resource was not found
 620       content:
 621         application/json:
 622           schema:
 623             $ref: '#/components/schemas/ErrorMessage'
 624           example:
 625             status: 400
 626             message: Not found error message
 627             details: Not found error details
 628     Unauthorized:
 629       description: Unauthorized
 630       content:
 631         application/json:
 632           schema:
 633             $ref: '#/components/schemas/ErrorMessage'
 634           example:
 635             status: 401
 636             message: Unauthorized error message
 637             details: Unauthorized error details
 638     Forbidden:
 639       description: Forbidden
 640       content:
 641         application/json:
 642           schema:
 643             $ref: '#/components/schemas/ErrorMessage'
 644           example:
 645             status: 403
 646             message: Forbidden error message
 647             details: Forbidden error details
 648     BadRequest:
 649       description: Bad Request
 650       content:
 651         application/json:
 652           schema:
 653             $ref: '#/components/schemas/ErrorMessage'
 654           example:
 655             status: 400 BAD_REQUEST
 656             message: Bad request error message
 657             details: Bad request error details
 658     Conflict:
 659       description: Conflict
 660       content:
 661         application/json:
 662           schema:
 663             $ref: '#/components/schemas/ErrorMessage'
 664           example:
 665             status: 409 CONFLICT
 666             message: Conflict error message
 667             details: Conflict error details
 668     NotImplemented:
 669       description: The given path has not been implemented
 670       content:
 671         application/json:
 672           schema:
 673             $ref: '#/components/schemas/ErrorMessage'
 674           example:
 675             status: 501
 676             message: Not implemented error message
 677             details: Not implemented error details
 678     Ok:
 679       description: OK
 680       content:
 681         application/json:
 682           schema:
 683             type: object
 684     Created:
 685       description: Created
 686       content: { }
 687     NoContent:
 688       description: No Content
 689       content: { }
 690     InternalServerError:
 691       description: Internal Server Error
 692       content:
 693         application/json:
 694           schema:
 695             $ref: "#/components/schemas/ErrorMessage"
 696           example:
 697             status: 500
 698             message: Internal Server Error
 699             details: Internal Server Error occurred
 700     BadGateway:
 701       description: Bad Gateway
 702       content:
 703         application/json:
 704           schema:
 705             $ref: "#/components/schemas/DmiErrorMessage"
 706           example:
 707             message: "Bad Gateway Error Message NCMP"
 708             dmi-response:
 709               http-code: 400
 710               body: "Bad Request"