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

   1 #  ============LICENSE_START=======================================================
   2 #  Copyright (C) 2021-2022 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
 172     CmHandleQueryParameters:
 173       type: object
 174       title: Cm Handle query parameters for executing cm handle search
 175       properties:
 176         cmHandleQueryParameters:
 177           type: array
 178           items:
 179             type: object
 180             $ref: '#/components/schemas/ConditionProperties'
 181         conditions:
 182           deprecated: true
 183           type: array
 184           items:
 185             type: object
 186             $ref: '#/components/schemas/OldConditionProperties'
 187           description: not necessary, it is just for backward compatibility
 188
 189     ConditionProperties:
 190       properties:
 191         conditionName:
 192           type: string
 193         conditionParameters:
 194           type: array
 195           items:
 196             type: object
 197             additionalProperties:
 198               type: string
 199     OldConditionProperties:
 200       deprecated: true
 201       properties:
 202         name:
 203           type: string
 204         conditionParameters:
 205           type: array
 206           items:
 207             type: object
 208             $ref: '#/components/schemas/ModuleNameAsJsonObject'
 209     ModuleNameAsJsonObject:
 210       properties:
 211         moduleName:
 212           type: string
 213           example: my-module
 214
 215     RestOutputCmHandle:
 216       type: object
 217       title: CM handle Details
 218       properties:
 219         cmHandle:
 220           type: string
 221           example: my-cm-handle1
 222         publicCmHandleProperties:
 223           $ref: '#/components/schemas/CmHandlePublicProperties'
 224         state:
 225           $ref: '#/components/schemas/CmHandleCompositeState'
 226     CmHandlePublicProperties:
 227       type: array
 228       items:
 229         type: object
 230         additionalProperties:
 231           type: string
 232           example: Book Type
 233     CmHandleCompositeState:
 234       type: object
 235       properties:
 236         cmHandleState:
 237           type: string
 238           example: ADVISED
 239         lockReason:
 240           $ref: '#/components/schemas/lock-reason'
 241         lastUpdateTime:
 242           type: string
 243           example: 2022-12-31T20:30:40.000+0000
 244         dataSyncEnabled:
 245           type: boolean
 246           example: false
 247         dataSyncState:
 248           $ref: '#/components/schemas/dataStores'
 249
 250     lock-reason:
 251       type: object
 252       properties:
 253         reason:
 254           type: string
 255           example: LOCKED_MISBEHAVING
 256         details:
 257           type: string
 258           example: locked due to failure in module sync
 259
 260     dataStores:
 261       type: object
 262       properties:
 263         operational:
 264           $ref: '#/components/schemas/sync-state'
 265         running:
 266           $ref: '#/components/schemas/sync-state'
 267
 268     sync-state:
 269       type: object
 270       properties:
 271         syncState:
 272           type: string
 273           example: NONE_REQUESTED
 274         lastSyncTime:
 275           type: string
 276           example: 2022-12-31T20:30:40.000+0000
 277
 278     RestOutputCmHandlePublicProperties:
 279       type: object
 280       properties:
 281         publicCmHandleProperties:
 282           $ref: '#/components/schemas/CmHandlePublicProperties'
 283
 284     RestOutputCmHandleCompositeState:
 285       type: object
 286       properties:
 287         state:
 288           $ref: '#/components/schemas/CmHandleCompositeState'
 289
 290   examples:
 291     dataSampleRequest:
 292         summary: Sample request
 293         description: Sample request body
 294         value:
 295           test:bookstore:
 296             bookstore-name: Chapters
 297             categories:
 298               - code: '01'
 299                 name: SciFi
 300                 books:
 301                 - authors:
 302                     - Iain M. Banks
 303                     - Ursula K. Le Guin
 304               - code: '02'
 305                 name: kids
 306                 books:
 307                 - authors:
 308                     - Philip Pullman
 309
 310     dataSamplePatchRequest:
 311       summary: Sample patch request
 312       description: Sample patch request body
 313       value:
 314         ietf-restconf:yang-patch:
 315           patch-id: patch-1
 316           edit:
 317             - edit-id: edit1
 318               operation: merge
 319               target: /
 320               value:
 321                 test:bookstore:
 322                   bookstore-name: Chapters
 323                   categories:
 324                     - code: '01'
 325                       name: Science
 326                       books:
 327                         - authors:
 328                             - Author1
 329                             - Author2
 330                     - code: '02'
 331                       name: Arts
 332                       books:
 333                         - authors:
 334                             - Author3
 335             - edit-id: edit2
 336               operation: merge
 337               target: /
 338               value:
 339                 test:bookstore:
 340                   bookstore-name: Novels
 341                   categories:
 342                     - code: '03'
 343                       name: History
 344                       books:
 345                         - authors:
 346                             - Iain M. Banks
 347                             - Ursula K. Le Guin
 348                     - code: '04'
 349                       name: Fiction
 350                       books:
 351                         - authors:
 352                             - Philip Pullman
 353
 354     dataSampleResponse:
 355         summary: Sample response
 356         description: Sample response for selecting 'sample 1'.
 357         value:
 358           bookstore:
 359             categories:
 360               - code: '01'
 361                 books:
 362                   - authors:
 363                       - Iain M. Banks
 364                       - Ursula K. Le Guin
 365                 name: SciFi
 366               - code: '02'
 367                 books:
 368                   - authors:
 369                       - Philip Pullman
 370                 name: kids
 371
 372     allCmHandleQueryParameters:
 373       value:
 374         cmHandleQueryParameters:
 375           - conditionName: hasAllModules
 376             conditionParameters:
 377               - { "moduleName": "my-module-1" }
 378               - { "moduleName": "my-module-2" }
 379               - { "moduleName": "my-module-3" }
 380           - conditionName: hasAllProperties
 381             conditionParameters:
 382               - { "Color": "yellow" }
 383               - { "Shape": "circle" }
 384               - { "Size": "small" }
 385           - conditionName: cmHandleWithCpsPath
 386             conditionParameters:
 387               - { "cpsPath": "//state[@cm-handle-state='ADVISED']" }
 388     pubPropCmHandleQueryParameters:
 389       value:
 390         cmHandleQueryParameters:
 391           - conditionName: hasAllProperties
 392             conditionParameters:
 393               - { "Color": "yellow" }
 394               - { "Shape": "circle" }
 395               - { "Size": "small" }
 396     modulesCmHandleQueryParameters:
 397       value:
 398         cmHandleQueryParameters:
 399           - conditionName: hasAllModules
 400             conditionParameters:
 401               - { "moduleName": "my-module-1" }
 402               - { "moduleName": "my-module-2" }
 403               - { "moduleName": "my-module-3" }
 404     cpsPathCmHandleStateQueryParameters:
 405       value:
 406         cmHandleQueryParameters:
 407           - conditionName: cmHandleWithCpsPath
 408             conditionParameters:
 409               - { "cpsPath": "//state[@cm-handle-state='LOCKED']" }
 410     cpsPathCmHandleDataSyncQueryParameters:
 411       value:
 412         cmHandleQueryParameters:
 413           - conditionName: cmHandleWithCpsPath
 414             conditionParameters:
 415               - { "cpsPath": "//state[@data-sync-enabled='true']" }
 416
 417   parameters:
 418     cmHandleInPath:
 419       name: cm-handle
 420       in: path
 421       description: The identifier for a network function, network element, subnetwork or any other cm object by managed Network CM Proxy
 422       required: true
 423       schema:
 424         type: string
 425         example: my-cm-handle
 426     dataSyncEnabled:
 427       name: dataSyncEnabled
 428       in: query
 429       description: Is used to enable or disable the data synchronization flag
 430       required: true
 431       schema:
 432         type: boolean
 433         example: true
 434     xpathInQuery:
 435       name: xpath
 436       in: query
 437       description: xpath
 438       required: false
 439       schema:
 440         type: string
 441         default: /
 442     requiredXpathInQuery:
 443       name: xpath
 444       in: query
 445       description: xpath
 446       required: true
 447       schema:
 448         type: string
 449     includeDescendantsOptionInQuery:
 450       name: include-descendants
 451       in: query
 452       description: include-descendants
 453       required: false
 454       schema:
 455         type: boolean
 456         default: false
 457     cpsPathInQuery:
 458       name: cps-path
 459       in: query
 460       description: cps-path
 461       required: false
 462       schema:
 463         type: string
 464         default: /
 465     resourceIdentifierInQuery:
 466       name: resourceIdentifier
 467       in: query
 468       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.
 469       required: true
 470       allowReserved: true
 471       schema:
 472         type: string
 473       examples:
 474         sample 1:
 475           value:
 476             resourceIdentifier: \shops\bookstore
 477         sample 2:
 478           value:
 479             resourceIdentifier: \shops\bookstore\categories[@code=1]
 480         sample 3:
 481           value:
 482             resourceIdentifier: parent=shops,child=bookstore
 483     optionsParamInQuery:
 484       name: options
 485       in: query
 486       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.
 487       required: false
 488       schema:
 489         type: string
 490       allowReserved: true
 491       examples:
 492         sample 1:
 493           value:
 494             options: (depth=3)
 495         sample 2:
 496           value:
 497             options: (fields=book)
 498         sample 3:
 499           value:
 500             options: (depth=2,fields=book/authors)
 501     topicParamInQuery:
 502       name: topic
 503       in: query
 504       description: topic parameter in query.
 505       required: false
 506       schema:
 507         type: string
 508       allowReserved: true
 509       examples:
 510         sample 1:
 511           value:
 512             topic: my-topic-name
 513     contentParamInHeader:
 514       name: Content-Type
 515       in: header
 516       required: false
 517       description: Content parameter for request, if content parameter is null, default value is application/json.
 518       schema:
 519         type: string
 520         default: application/json
 521         example: application/yang-data+json
 522
 523   responses:
 524     NotFound:
 525       description: The specified resource was not found
 526       content:
 527         application/json:
 528           schema:
 529             $ref: '#/components/schemas/ErrorMessage'
 530           example:
 531             status: 400
 532             message: Not found error message
 533             details: Not found error details
 534     Unauthorized:
 535       description: Unauthorized
 536       content:
 537         application/json:
 538           schema:
 539             $ref: '#/components/schemas/ErrorMessage'
 540           example:
 541             status: 401
 542             message: Unauthorized error message
 543             details: Unauthorized error details
 544     Forbidden:
 545       description: Forbidden
 546       content:
 547         application/json:
 548           schema:
 549             $ref: '#/components/schemas/ErrorMessage'
 550           example:
 551            status: 403
 552            message: Forbidden error message
 553            details: Forbidden error details
 554     BadRequest:
 555       description: Bad Request
 556       content:
 557         application/json:
 558           schema:
 559             $ref: '#/components/schemas/ErrorMessage'
 560           example:
 561            status: 400 BAD_REQUEST
 562            message: Bad request error message
 563            details: Bad request error details
 564     Conflict:
 565       description: Conflict
 566       content:
 567         application/json:
 568           schema:
 569             $ref: '#/components/schemas/ErrorMessage'
 570           example:
 571            status: 409 CONFLICT
 572            message: Conflict error message
 573            details: Conflict error details
 574     NotImplemented:
 575       description: The given path has not been implemented
 576       content:
 577         application/json:
 578           schema:
 579             $ref: '#/components/schemas/ErrorMessage'
 580           example:
 581            status: 501
 582            message: Not implemented error message
 583            details: Not implemented error details
 584     Ok:
 585       description: OK
 586       content:
 587         application/json:
 588           schema:
 589             type: object
 590     Created:
 591       description: Created
 592       content: {}
 593     NoContent:
 594       description: No Content
 595       content: {}
 596     InternalServerError:
 597       description: Internal Server Error
 598       content:
 599         application/json:
 600           schema:
 601             $ref: "#/components/schemas/ErrorMessage"
 602           example:
 603             status: 500
 604             message: Internal Server Error
 605             details: Internal Server Error occurred
 606     BadGateway:
 607       description: Bad Gateway
 608       content:
 609         application/json:
 610           schema:
 611             $ref: "#/components/schemas/DmiErrorMessage"
 612           example:
 613             message: "Bad Gateway Error Message NCMP"
 614             dmi-response:
 615               http-code: 400
 616               body: "Bad Request"