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     CmHandlePublicProperties:
 246       type: object
 247       items:
 248         type: object
 249         additionalProperties:
 250           type: string
 251           example: 'Book Type'
 252     CmHandleCompositeState:
 253       type: object
 254       properties:
 255         cmHandleState:
 256           type: string
 257           example: ADVISED
 258         lockReason:
 259           $ref: '#/components/schemas/lock-reason'
 260         lastUpdateTime:
 261           type: string
 262           example: 2022-12-31T20:30:40.000+0000
 263         dataSyncEnabled:
 264           type: boolean
 265           example: false
 266         dataSyncState:
 267           $ref: '#/components/schemas/dataStores'
 268
 269     lock-reason:
 270       type: object
 271       properties:
 272         reason:
 273           type: string
 274           example: LOCKED_MISBEHAVING
 275         details:
 276           type: string
 277           example: locked due to failure in module sync
 278
 279     dataStores:
 280       type: object
 281       properties:
 282         operational:
 283           $ref: '#/components/schemas/sync-state'
 284         running:
 285           $ref: '#/components/schemas/sync-state'
 286
 287     sync-state:
 288       type: object
 289       properties:
 290         syncState:
 291           type: string
 292           example: NONE_REQUESTED
 293         lastSyncTime:
 294           type: string
 295           example: 2022-12-31T20:30:40.000+0000
 296
 297     RestOutputCmHandlePublicProperties:
 298       type: object
 299       properties:
 300         publicCmHandleProperties:
 301           $ref: '#/components/schemas/CmHandlePublicProperties'
 302
 303     RestOutputCmHandleCompositeState:
 304       type: object
 305       properties:
 306         state:
 307           $ref: '#/components/schemas/CmHandleCompositeState'
 308     # Data Operation Request Schemas
 309     DataOperationRequest:
 310       type: object
 311       title: execute data operation for given array of operations
 312       properties:
 313         operations:
 314           type: array
 315           items:
 316             $ref: '#/components/schemas/DataOperationDefinition'
 317           description: contains group of data operation requests
 318     DataOperationDefinition:
 319       required:
 320         - operation
 321         - datastore
 322         - operationId
 323       properties:
 324         operation:
 325           type: string
 326           example: 'read'
 327         operationId:
 328           type: string
 329           example: '12'
 330         datastore:
 331           type: string
 332           example: 'ncmp-datastore:passthrough-operational'
 333         options:
 334           type: string
 335           example: '(fields=schemas/schema)'
 336         resourceIdentifier:
 337           type: string
 338           example: 'parent/child'
 339         targetIds:
 340           type: array
 341           items:
 342             type: string
 343             example: [ "da310eecdb8d44c2acc0ddaae01174b1","c748c58f8e0b438f9fd1f28370b17d47" ]
 344
 345   examples:
 346     dataSampleRequest:
 347       summary: Sample request
 348       description: Sample request body
 349       value:
 350         test:bookstore:
 351           bookstore-name: Chapters
 352           categories:
 353             - code: '01'
 354               name: SciFi
 355               books:
 356                 - authors:
 357                     - Iain M. Banks
 358                     - Ursula K. Le Guin
 359             - code: '02'
 360               name: kids
 361               books:
 362                 - authors:
 363                     - Philip Pullman
 364
 365     dataSamplePatchRequest:
 366       summary: Sample patch request
 367       description: Sample patch request body
 368       value:
 369         ietf-restconf:yang-patch:
 370           patch-id: patch-1
 371           edit:
 372             - edit-id: edit1
 373               operation: merge
 374               target: /
 375               value:
 376                 test:bookstore:
 377                   bookstore-name: Chapters
 378                   categories:
 379                     - code: '01'
 380                       name: Science
 381                       books:
 382                         - authors:
 383                             - Author1
 384                             - Author2
 385                     - code: '02'
 386                       name: Arts
 387                       books:
 388                         - authors:
 389                             - Author3
 390             - edit-id: edit2
 391               operation: merge
 392               target: /
 393               value:
 394                 test:bookstore:
 395                   bookstore-name: Novels
 396                   categories:
 397                     - code: '03'
 398                       name: History
 399                       books:
 400                         - authors:
 401                             - Iain M. Banks
 402                             - Ursula K. Le Guin
 403                     - code: '04'
 404                       name: Fiction
 405                       books:
 406                         - authors:
 407                             - Philip Pullman
 408
 409     dataSampleResponse:
 410       summary: Sample response
 411       description: Sample response for selecting 'sample 1'.
 412       value:
 413         bookstore:
 414           categories:
 415             - code: '01'
 416               books:
 417                 - authors:
 418                     - Iain M. Banks
 419                     - Ursula K. Le Guin
 420               name: SciFi
 421             - code: '02'
 422               books:
 423                 - authors:
 424                     - Philip Pullman
 425               name: kids
 426
 427     allCmHandleQueryParameters:
 428       value:
 429         cmHandleQueryParameters:
 430           - conditionName: hasAllModules
 431             conditionParameters:
 432               - { "moduleName": "my-module-1" }
 433               - { "moduleName": "my-module-2" }
 434               - { "moduleName": "my-module-3" }
 435           - conditionName: hasAllProperties
 436             conditionParameters:
 437               - { "Color": "yellow" }
 438               - { "Shape": "circle" }
 439               - { "Size": "small" }
 440           - conditionName: cmHandleWithCpsPath
 441             conditionParameters:
 442               - { "cpsPath": "//state[@cm-handle-state='ADVISED']" }
 443     pubPropCmHandleQueryParameters:
 444       value:
 445         cmHandleQueryParameters:
 446           - conditionName: hasAllProperties
 447             conditionParameters:
 448               - { "Color": "yellow" }
 449               - { "Shape": "circle" }
 450               - { "Size": "small" }
 451     modulesCmHandleQueryParameters:
 452       value:
 453         cmHandleQueryParameters:
 454           - conditionName: hasAllModules
 455             conditionParameters:
 456               - { "moduleName": "my-module-1" }
 457               - { "moduleName": "my-module-2" }
 458               - { "moduleName": "my-module-3" }
 459     cpsPathCmHandleStateQueryParameters:
 460       value:
 461         cmHandleQueryParameters:
 462           - conditionName: cmHandleWithCpsPath
 463             conditionParameters:
 464               - { "cpsPath": "//state[@cm-handle-state='LOCKED']" }
 465     cpsPathCmHandleDataSyncQueryParameters:
 466       value:
 467         cmHandleQueryParameters:
 468           - conditionName: cmHandleWithCpsPath
 469             conditionParameters:
 470               - { "cpsPath": "//state[@data-sync-enabled='true']" }
 471
 472   parameters:
 473     cmHandleInPath:
 474       name: cm-handle
 475       in: path
 476       description: The identifier for a network function, network element, subnetwork or any other cm object by managed Network CM Proxy
 477       required: true
 478       schema:
 479         type: string
 480         example: my-cm-handle
 481     dataSyncEnabled:
 482       name: dataSyncEnabled
 483       in: query
 484       description: Is used to enable or disable the data synchronization flag
 485       required: true
 486       schema:
 487         type: boolean
 488         example: true
 489     xpathInQuery:
 490       name: xpath
 491       in: query
 492       description: xpath
 493       required: false
 494       schema:
 495         type: string
 496         default: /
 497     requiredXpathInQuery:
 498       name: xpath
 499       in: query
 500       description: xpath
 501       required: true
 502       schema:
 503         type: string
 504     includeDescendantsOptionInQuery:
 505       name: include-descendants
 506       in: query
 507       description: Determines if descendants are included in response
 508       required: false
 509       schema:
 510         type: boolean
 511         default: false
 512     cpsPathInQuery:
 513       name: cps-path
 514       in: query
 515       description: For more details on cps path, please refer https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html
 516       required: false
 517       schema:
 518         type: string
 519         default: /
 520       examples:
 521         container cps path:
 522           value: //bookstore
 523         list attributes cps path:
 524           value: //categories[@code=1]
 525     dmiPluginIdentifierInQuery:
 526       name: dmi-plugin-identifier
 527       in: query
 528       description: dmi-plugin-identifier
 529       required: true
 530       schema:
 531         type: string
 532         example: my-dmi-plugin
 533     resourceIdentifierInQuery:
 534       name: resourceIdentifier
 535       in: query
 536       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.
 537       required: true
 538       allowReserved: true
 539       schema:
 540         type: string
 541       examples:
 542         sample 1:
 543           value:
 544             resourceIdentifier: \shops\bookstore
 545         sample 2:
 546           value:
 547             resourceIdentifier: \shops\bookstore\categories[@code=1]
 548         sample 3:
 549           value:
 550             resourceIdentifier: parent=shops,child=bookstore
 551     optionsParamInQuery:
 552       name: options
 553       in: query
 554       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.
 555       required: false
 556       schema:
 557         type: string
 558       allowReserved: true
 559       examples:
 560         sample 1:
 561           value:
 562             options: (depth=3)
 563         sample 2:
 564           value:
 565             options: (fields=book)
 566         sample 3:
 567           value:
 568             options: (depth=2,fields=book/authors)
 569     topicParamInQuery:
 570       name: topic
 571       in: query
 572       description: topic parameter in query.
 573       required: false
 574       schema:
 575         type: string
 576       allowReserved: true
 577       examples:
 578         sample 1:
 579           value:
 580             topic: my-topic-name
 581     requiredTopicParamInQuery:
 582       name: topic
 583       in: query
 584       description: mandatory topic parameter in query.
 585       required: true
 586       schema:
 587         type: string
 588       allowReserved: true
 589       examples:
 590         sample 1:
 591           value:
 592             topic: my-topic-name
 593     contentParamInHeader:
 594       name: Content-Type
 595       in: header
 596       required: false
 597       description: Content parameter for request, if content parameter is null, default value is application/json.
 598       schema:
 599         type: string
 600         default: application/json
 601         example: application/yang-data+json
 602     datastoreName:
 603       name: datastore-name
 604       in: path
 605       description: The type of the requested data
 606       required: true
 607       schema:
 608         type: string
 609         example: ncmp-datastore:running
 610
 611   responses:
 612     NotFound:
 613       description: The specified resource was not found
 614       content:
 615         application/json:
 616           schema:
 617             $ref: '#/components/schemas/ErrorMessage'
 618           example:
 619             status: 400
 620             message: Not found error message
 621             details: Not found error details
 622     Unauthorized:
 623       description: Unauthorized
 624       content:
 625         application/json:
 626           schema:
 627             $ref: '#/components/schemas/ErrorMessage'
 628           example:
 629             status: 401
 630             message: Unauthorized error message
 631             details: Unauthorized error details
 632     Forbidden:
 633       description: Forbidden
 634       content:
 635         application/json:
 636           schema:
 637             $ref: '#/components/schemas/ErrorMessage'
 638           example:
 639             status: 403
 640             message: Forbidden error message
 641             details: Forbidden error details
 642     BadRequest:
 643       description: Bad Request
 644       content:
 645         application/json:
 646           schema:
 647             $ref: '#/components/schemas/ErrorMessage'
 648           example:
 649             status: 400 BAD_REQUEST
 650             message: Bad request error message
 651             details: Bad request error details
 652     Conflict:
 653       description: Conflict
 654       content:
 655         application/json:
 656           schema:
 657             $ref: '#/components/schemas/ErrorMessage'
 658           example:
 659             status: 409 CONFLICT
 660             message: Conflict error message
 661             details: Conflict error details
 662     NotImplemented:
 663       description: The given path has not been implemented
 664       content:
 665         application/json:
 666           schema:
 667             $ref: '#/components/schemas/ErrorMessage'
 668           example:
 669             status: 501
 670             message: Not implemented error message
 671             details: Not implemented error details
 672     Ok:
 673       description: OK
 674       content:
 675         application/json:
 676           schema:
 677             type: object
 678     Created:
 679       description: Created
 680       content: { }
 681     NoContent:
 682       description: No Content
 683       content: { }
 684     InternalServerError:
 685       description: Internal Server Error
 686       content:
 687         application/json:
 688           schema:
 689             $ref: "#/components/schemas/ErrorMessage"
 690           example:
 691             status: 500
 692             message: Internal Server Error
 693             details: Internal Server Error occurred
 694     BadGateway:
 695       description: Bad Gateway
 696       content:
 697         application/json:
 698           schema:
 699             $ref: "#/components/schemas/DmiErrorMessage"
 700           example:
 701             message: "Bad Gateway Error Message NCMP"
 702             dmi-response:
 703               http-code: 400
 704               body: "Bad Request"