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

   1 #  ============LICENSE_START=======================================================
   2 #  Copyright (C) 2021-2024 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         trustLevel:
 140             type: string
 141             enum: [COMPLETE, NONE]
 142             example: "COMPLETE"
 143         alternateId:
 144           type: string
 145           example: "my-alternate-id"
 146         dataProducerIdentifier:
 147           type: string
 148           example: "my-data-producer-identifier"
 149     RestCmHandleProperties:
 150       type: object
 151       additionalProperties:
 152         type: string
 153         example: my-property
 154     #Module upgrade schema
 155     UpgradedCmHandles:
 156       required:
 157         - cmHandles
 158       type: object
 159       properties:
 160         cmHandles:
 161           type: array
 162           items:
 163             type: string
 164           example: [ my-cm-handle1, my-cm-handle2, my-cm-handle3 ]
 165         moduleSetTag:
 166           type: string
 167           default: ""
 168           example: 'my-module-set-tag'
 169
 170     #Response Schemas
 171     RestModuleReference:
 172       type: object
 173       title: Module reference details
 174       properties:
 175         moduleName:
 176           type: string
 177           example: my-module-name
 178         revision:
 179           type: string
 180           example: my-module-revision
 181
 182     RestModuleDefinition:
 183       type: object
 184       title: Module definitions
 185       properties:
 186         moduleName:
 187           type: string
 188           example: my-module-name
 189         revision:
 190           type: string
 191           example: 2020-09-15
 192         content:
 193           type: string
 194           example: |
 195             module stores {
 196               yang-version 1.1;
 197               namespace 'org:onap:ccsdk:sample';
 198               prefix book-store;
 199               revision '2020-09-15' {
 200                 description
 201                 'Sample Model';
 202               }
 203             }
 204
 205     CmHandleQueryParameters:
 206       type: object
 207       title: Cm Handle query parameters for executing cm handle search
 208       properties:
 209         cmHandleQueryParameters:
 210           type: array
 211           items:
 212             $ref: '#/components/schemas/ConditionProperties'
 213         conditions:
 214           deprecated: true
 215           type: array
 216           items:
 217             $ref: '#/components/schemas/OldConditionProperties'
 218           description: not necessary, it is just for backward compatibility
 219
 220     ConditionProperties:
 221       properties:
 222         conditionName:
 223           type: string
 224         conditionParameters:
 225           type: array
 226           items:
 227             type: object
 228             additionalProperties:
 229               type: string
 230     OldConditionProperties:
 231       deprecated: true
 232       properties:
 233         name:
 234           type: string
 235         conditionParameters:
 236           type: array
 237           items:
 238             $ref: '#/components/schemas/ModuleNameAsJsonObject'
 239     ModuleNameAsJsonObject:
 240       properties:
 241         moduleName:
 242           type: string
 243           example: my-module
 244
 245     RestOutputCmHandle:
 246       type: object
 247       title: CM handle Details
 248       properties:
 249         cmHandle:
 250           type: string
 251           example: my-cm-handle1
 252         publicCmHandleProperties:
 253           $ref: '#/components/schemas/CmHandlePublicProperties'
 254         state:
 255           $ref: '#/components/schemas/CmHandleCompositeState'
 256         trustLevel:
 257           $ref: '#/components/schemas/CmHandleTrustLevel'
 258     CmHandlePublicProperties:
 259       type: object
 260       items:
 261         type: object
 262         additionalProperties:
 263           type: string
 264           example: 'Book Type'
 265     CmHandleCompositeState:
 266       type: object
 267       properties:
 268         cmHandleState:
 269           type: string
 270           example: ADVISED
 271         lockReason:
 272           $ref: '#/components/schemas/lock-reason'
 273         lastUpdateTime:
 274           type: string
 275           example: 2022-12-31T20:30:40.000+0000
 276         dataSyncEnabled:
 277           type: boolean
 278           example: false
 279         dataSyncState:
 280           $ref: '#/components/schemas/dataStores'
 281     CmHandleTrustLevel:
 282       type: string
 283       description: Current trust level of the relevant CM handle ID.
 284       example: COMPLETE
 285
 286     lock-reason:
 287       type: object
 288       properties:
 289         reason:
 290           type: string
 291           example: LOCKED_MISBEHAVING
 292         details:
 293           type: string
 294           example: locked due to failure in module sync
 295
 296     dataStores:
 297       type: object
 298       properties:
 299         operational:
 300           $ref: '#/components/schemas/sync-state'
 301         running:
 302           $ref: '#/components/schemas/sync-state'
 303
 304     sync-state:
 305       type: object
 306       properties:
 307         syncState:
 308           type: string
 309           example: NONE_REQUESTED
 310         lastSyncTime:
 311           type: string
 312           example: 2022-12-31T20:30:40.000+0000
 313
 314     RestOutputCmHandlePublicProperties:
 315       type: object
 316       properties:
 317         publicCmHandleProperties:
 318           $ref: '#/components/schemas/CmHandlePublicProperties'
 319
 320     RestOutputCmHandleCompositeState:
 321       type: object
 322       properties:
 323         state:
 324           $ref: '#/components/schemas/CmHandleCompositeState'
 325     # Data Operation Request Schemas
 326     DataOperationRequest:
 327       type: object
 328       title: execute data operation for given array of operations
 329       properties:
 330         operations:
 331           type: array
 332           items:
 333             $ref: '#/components/schemas/DataOperationDefinition'
 334           description: contains group of data operation requests
 335     DataOperationDefinition:
 336       required:
 337         - operation
 338         - datastore
 339         - operationId
 340       properties:
 341         operation:
 342           type: string
 343           example: 'read'
 344         operationId:
 345           type: string
 346           example: '12'
 347         datastore:
 348           type: string
 349           example: 'ncmp-datastore:passthrough-operational'
 350         options:
 351           type: string
 352           example: '(fields=schemas/schema)'
 353         resourceIdentifier:
 354           type: string
 355           example: 'parent/child'
 356         targetIds:
 357           type: array
 358           items:
 359             type: string
 360             example: [ "da310eecdb8d44c2acc0ddaae01174b1","c748c58f8e0b438f9fd1f28370b17d47" ]
 361
 362   examples:
 363     dataSampleRequest:
 364       summary: Sample request
 365       description: Sample request body
 366       value:
 367         test:bookstore:
 368           bookstore-name: Chapters
 369           categories:
 370             - code: '01'
 371               name: SciFi
 372               books:
 373                 - authors:
 374                     - Iain M. Banks
 375                     - Ursula K. Le Guin
 376             - code: '02'
 377               name: kids
 378               books:
 379                 - authors:
 380                     - Philip Pullman
 381
 382     dataSamplePatchRequest:
 383       summary: Sample patch request
 384       description: Sample patch request body
 385       value:
 386         ietf-restconf:yang-patch:
 387           patch-id: patch-1
 388           edit:
 389             - edit-id: edit1
 390               operation: merge
 391               target: /
 392               value:
 393                 test:bookstore:
 394                   bookstore-name: Chapters
 395                   categories:
 396                     - code: '01'
 397                       name: Science
 398                       books:
 399                         - authors:
 400                             - Author1
 401                             - Author2
 402                     - code: '02'
 403                       name: Arts
 404                       books:
 405                         - authors:
 406                             - Author3
 407             - edit-id: edit2
 408               operation: merge
 409               target: /
 410               value:
 411                 test:bookstore:
 412                   bookstore-name: Novels
 413                   categories:
 414                     - code: '03'
 415                       name: History
 416                       books:
 417                         - authors:
 418                             - Iain M. Banks
 419                             - Ursula K. Le Guin
 420                     - code: '04'
 421                       name: Fiction
 422                       books:
 423                         - authors:
 424                             - Philip Pullman
 425
 426     dataSampleResponse:
 427       summary: Sample response
 428       description: Sample response for selecting 'sample 1'.
 429       value:
 430         bookstore:
 431           categories:
 432             - code: '01'
 433               books:
 434                 - authors:
 435                     - Iain M. Banks
 436                     - Ursula K. Le Guin
 437               name: SciFi
 438             - code: '02'
 439               books:
 440                 - authors:
 441                     - Philip Pullman
 442               name: kids
 443
 444     allCmHandleQueryParameters:
 445       value:
 446         cmHandleQueryParameters:
 447           - conditionName: hasAllModules
 448             conditionParameters:
 449               - { "moduleName": "my-module-1" }
 450               - { "moduleName": "my-module-2" }
 451               - { "moduleName": "my-module-3" }
 452           - conditionName: hasAllProperties
 453             conditionParameters:
 454               - { "Color": "yellow" }
 455               - { "Shape": "circle" }
 456               - { "Size": "small" }
 457           - conditionName: cmHandleWithCpsPath
 458             conditionParameters:
 459               - { "cpsPath": "//state[@cm-handle-state='ADVISED']" }
 460     pubPropCmHandleQueryParameters:
 461       value:
 462         cmHandleQueryParameters:
 463           - conditionName: hasAllProperties
 464             conditionParameters:
 465               - { "Color": "yellow" }
 466               - { "Shape": "circle" }
 467               - { "Size": "small" }
 468     modulesCmHandleQueryParameters:
 469       value:
 470         cmHandleQueryParameters:
 471           - conditionName: hasAllModules
 472             conditionParameters:
 473               - { "moduleName": "my-module-1" }
 474               - { "moduleName": "my-module-2" }
 475               - { "moduleName": "my-module-3" }
 476     cpsPathCmHandleStateQueryParameters:
 477       value:
 478         cmHandleQueryParameters:
 479           - conditionName: cmHandleWithCpsPath
 480             conditionParameters:
 481               - { "cpsPath": "//state[@cm-handle-state='LOCKED']" }
 482     cpsPathCmHandleDataSyncQueryParameters:
 483       value:
 484         cmHandleQueryParameters:
 485           - conditionName: cmHandleWithCpsPath
 486             conditionParameters:
 487               - { "cpsPath": "//state[@data-sync-enabled='true']" }
 488
 489   parameters:
 490     cmHandleInPath:
 491       name: cm-handle
 492       in: path
 493       description: The identifier for a network function, network element, subnetwork or any other cm object by managed Network CM Proxy
 494       required: true
 495       schema:
 496         type: string
 497         example: my-cm-handle
 498     moduleNameInQuery:
 499       name: module-name
 500       in: query
 501       description: Filter for a module name.This is an optional parameter
 502       required: false
 503       schema:
 504         type: string
 505         example: my-module
 506     revisionInQuery:
 507       name: revision
 508       in: query
 509       description: Filter for a module revision.This is an optional parameter and ignored when no module name is supplied
 510       required: false
 511       schema:
 512         type: string
 513         example: 2024-01-22
 514     dataSyncEnabled:
 515       name: dataSyncEnabled
 516       in: query
 517       description: Is used to enable or disable the data synchronization flag
 518       required: true
 519       schema:
 520         type: boolean
 521         example: true
 522     xpathInQuery:
 523       name: xpath
 524       in: query
 525       description: xpath
 526       required: false
 527       schema:
 528         type: string
 529         default: /
 530     requiredXpathInQuery:
 531       name: xpath
 532       in: query
 533       description: xpath
 534       required: true
 535       schema:
 536         type: string
 537     includeDescendantsOptionInQuery:
 538       name: include-descendants
 539       in: query
 540       description: Determines if descendants are included in response
 541       required: false
 542       schema:
 543         type: boolean
 544         default: false
 545     cpsPathInQuery:
 546       name: cps-path
 547       in: query
 548       description: For more details on cps path, please refer https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html
 549       required: false
 550       schema:
 551         type: string
 552         default: /
 553       examples:
 554         container cps path:
 555           value: //bookstore
 556         list attributes cps path:
 557           value: //categories[@code=1]
 558     dmiPluginIdentifierInQuery:
 559       name: dmi-plugin-identifier
 560       in: query
 561       description: dmi-plugin-identifier
 562       required: true
 563       schema:
 564         type: string
 565         example: my-dmi-plugin
 566     resourceIdentifierInQuery:
 567       name: resourceIdentifier
 568       in: query
 569       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.
 570       required: true
 571       allowReserved: true
 572       schema:
 573         type: string
 574       examples:
 575         sample 1:
 576           value:
 577             resourceIdentifier: \shops\bookstore
 578         sample 2:
 579           value:
 580             resourceIdentifier: \shops\bookstore\categories[@code=1]
 581         sample 3:
 582           value:
 583             resourceIdentifier: parent=shops,child=bookstore
 584     optionsParamInQuery:
 585       name: options
 586       in: query
 587       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.
 588       required: false
 589       schema:
 590         type: string
 591       allowReserved: true
 592       examples:
 593         sample 1:
 594           value:
 595             options: (depth=3)
 596         sample 2:
 597           value:
 598             options: (fields=book)
 599         sample 3:
 600           value:
 601             options: (depth=2,fields=book/authors)
 602     topicParamInQuery:
 603       name: topic
 604       in: query
 605       description: topic parameter in query.
 606       required: false
 607       schema:
 608         type: string
 609       allowReserved: true
 610       examples:
 611         sample 1:
 612           value:
 613             topic: my-topic-name
 614     requiredTopicParamInQuery:
 615       name: topic
 616       in: query
 617       description: mandatory topic parameter in query.
 618       required: true
 619       schema:
 620         type: string
 621       allowReserved: true
 622       examples:
 623         sample 1:
 624           value:
 625             topic: my-topic-name
 626     contentParamInHeader:
 627       name: Content-Type
 628       in: header
 629       required: false
 630       description: Content parameter for request, if content parameter is null, default value is application/json.
 631       schema:
 632         type: string
 633         default: application/json
 634         example: application/yang-data+json
 635     authorizationParamInHeader:
 636       name: Authorization
 637       in: header
 638       required: false
 639       description: Authorization parameter for request.
 640       schema:
 641         type: string
 642     datastoreName:
 643       name: datastore-name
 644       in: path
 645       description: The type of the requested data
 646       required: true
 647       schema:
 648         type: string
 649         example: ncmp-datastore:running
 650
 651   responses:
 652     NotFound:
 653       description: The specified resource was not found
 654       content:
 655         application/json:
 656           schema:
 657             $ref: '#/components/schemas/ErrorMessage'
 658           example:
 659             status: 400
 660             message: Not found error message
 661             details: Not found error details
 662     Unauthorized:
 663       description: Unauthorized
 664       content:
 665         application/json:
 666           schema:
 667             $ref: '#/components/schemas/ErrorMessage'
 668           example:
 669             status: 401
 670             message: Unauthorized error message
 671             details: Unauthorized error details
 672     Forbidden:
 673       description: Forbidden
 674       content:
 675         application/json:
 676           schema:
 677             $ref: '#/components/schemas/ErrorMessage'
 678           example:
 679             status: 403
 680             message: Forbidden error message
 681             details: Forbidden error details
 682     BadRequest:
 683       description: Bad Request
 684       content:
 685         application/json:
 686           schema:
 687             $ref: '#/components/schemas/ErrorMessage'
 688           example:
 689             status: 400 BAD_REQUEST
 690             message: Bad request error message
 691             details: Bad request error details
 692     Conflict:
 693       description: Conflict
 694       content:
 695         application/json:
 696           schema:
 697             $ref: '#/components/schemas/ErrorMessage'
 698           example:
 699             status: 409 CONFLICT
 700             message: Conflict error message
 701             details: Conflict error details
 702     NotImplemented:
 703       description: The given path has not been implemented
 704       content:
 705         application/json:
 706           schema:
 707             $ref: '#/components/schemas/ErrorMessage'
 708           example:
 709             status: 501
 710             message: Not implemented error message
 711             details: Not implemented error details
 712     Ok:
 713       description: OK
 714       content:
 715         application/json:
 716           schema:
 717             type: object
 718     Created:
 719       description: Created
 720       content: { }
 721     NoContent:
 722       description: No Content
 723       content: { }
 724     InternalServerError:
 725       description: Internal Server Error
 726       content:
 727         application/json:
 728           schema:
 729             $ref: "#/components/schemas/ErrorMessage"
 730           example:
 731             status: 500
 732             message: Internal Server Error
 733             details: Internal Server Error occurred
 734     BadGateway:
 735       description: Bad Gateway
 736       content:
 737         application/json:
 738           schema:
 739             $ref: "#/components/schemas/DmiErrorMessage"
 740           example:
 741             message: "Bad Gateway Error Message NCMP"
 742             dmi-response:
 743               http-code: 400
 744               body: "Bad Request"