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