cps-ncmp-rest/docs/openapi/ncmp.yml

   1 #  ============LICENSE_START=======================================================
   2 #  Copyright (C) 2021-2025 OpenInfra Foundation Europe. All rights reserved.
   3 #  Modifications Copyright (C) 2021 Pantheon.tech
   4 #  Modifications Copyright (C) 2021-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 resourceDataForCmHandle:
  22   get:
  23     tags:
  24       - network-cm-proxy
  25     summary: Get resource data for cm handle
  26     description: Get resource data for given cm handle
  27     operationId: getResourceDataForCmHandle
  28     parameters:
  29       - $ref: 'components.yaml#/components/parameters/datastoreName'
  30       - $ref: 'components.yaml#/components/parameters/cmHandleReferenceInPath'
  31       - $ref: 'components.yaml#/components/parameters/resourceIdentifierInQuery'
  32       - $ref: 'components.yaml#/components/parameters/optionsParamInQuery'
  33       - $ref: 'components.yaml#/components/parameters/topicParamInQuery'
  34       - $ref: 'components.yaml#/components/parameters/includeDescendantsOptionInQuery'
  35       - $ref: 'components.yaml#/components/parameters/authorizationParamInHeader'
  36     responses:
  37       200:
  38         description: OK
  39         content:
  40           application/json:
  41             schema:
  42               type: object
  43             examples:
  44               dataSampleResponse:
  45                 $ref: 'components.yaml#/components/examples/dataSampleResponse'
  46       400:
  47         $ref: 'components.yaml#/components/responses/BadRequest'
  48       403:
  49         $ref: 'components.yaml#/components/responses/Forbidden'
  50       500:
  51         $ref: 'components.yaml#/components/responses/InternalServerError'
  52       502:
  53         $ref: 'components.yaml#/components/responses/BadGateway'
  54
  55   post:
  56     tags:
  57       - network-cm-proxy
  58     summary: create resource data from pass-through running for cm handle
  59     description: create resource data from pass-through running for given cm handle
  60     operationId: createResourceDataRunningForCmHandle
  61     parameters:
  62       - $ref: 'components.yaml#/components/parameters/datastoreName'
  63       - $ref: 'components.yaml#/components/parameters/cmHandleReferenceInPath'
  64       - $ref: 'components.yaml#/components/parameters/resourceIdentifierInQuery'
  65       - $ref: 'components.yaml#/components/parameters/contentParamInHeader'
  66       - $ref: 'components.yaml#/components/parameters/authorizationParamInHeader'
  67     requestBody:
  68       required: true
  69       content:
  70         application/json:
  71           schema:
  72             type: object
  73           examples:
  74             dataSampleRequest:
  75               $ref: 'components.yaml#/components/examples/dataSampleRequest'
  76         application/yang-data+json:
  77           schema:
  78             type: object
  79           examples:
  80             dataSampleRequest:
  81               $ref: 'components.yaml#/components/examples/dataSampleRequest'
  82     responses:
  83       201:
  84         $ref: 'components.yaml#/components/responses/Created'
  85       400:
  86         $ref: 'components.yaml#/components/responses/BadRequest'
  87       403:
  88         $ref: 'components.yaml#/components/responses/Forbidden'
  89       409:
  90         $ref: 'components.yaml#/components/responses/Conflict'
  91       500:
  92         $ref: 'components.yaml#/components/responses/InternalServerError'
  93       502:
  94         $ref: 'components.yaml#/components/responses/BadGateway'
  95
  96   put:
  97     tags:
  98       - network-cm-proxy
  99     summary: Update resource data from pass-through running for a cm handle
 100     description: Update resource data from pass-through running for the given cm handle
 101     operationId: updateResourceDataRunningForCmHandle
 102     parameters:
 103       - $ref: 'components.yaml#/components/parameters/datastoreName'
 104       - $ref: 'components.yaml#/components/parameters/cmHandleReferenceInPath'
 105       - $ref: 'components.yaml#/components/parameters/resourceIdentifierInQuery'
 106       - $ref: 'components.yaml#/components/parameters/contentParamInHeader'
 107       - $ref: 'components.yaml#/components/parameters/authorizationParamInHeader'
 108     requestBody:
 109       required: true
 110       content:
 111         application/json:
 112           schema:
 113             type: object
 114           examples:
 115             dataSampleRequest:
 116               $ref: 'components.yaml#/components/examples/dataSampleRequest'
 117         application/yang-data+json:
 118           schema:
 119             type: object
 120           examples:
 121             dataSampleRequest:
 122               $ref: 'components.yaml#/components/examples/dataSampleRequest'
 123     responses:
 124       200:
 125         $ref: 'components.yaml#/components/responses/Ok'
 126       400:
 127         $ref: 'components.yaml#/components/responses/BadRequest'
 128       403:
 129         $ref: 'components.yaml#/components/responses/Forbidden'
 130       409:
 131         $ref: 'components.yaml#/components/responses/Conflict'
 132       500:
 133         $ref: 'components.yaml#/components/responses/InternalServerError'
 134       502:
 135         $ref: 'components.yaml#/components/responses/BadGateway'
 136
 137   patch:
 138     tags:
 139       - network-cm-proxy
 140     summary: Patch resource data from pass-through running
 141     description: Patch resource data from pass-through running for the given cm handle
 142     operationId: patchResourceDataRunningForCmHandle
 143     parameters:
 144       - $ref: 'components.yaml#/components/parameters/datastoreName'
 145       - $ref: 'components.yaml#/components/parameters/cmHandleReferenceInPath'
 146       - $ref: 'components.yaml#/components/parameters/resourceIdentifierInQuery'
 147       - $ref: 'components.yaml#/components/parameters/contentParamInHeader'
 148       - $ref: 'components.yaml#/components/parameters/authorizationParamInHeader'
 149     requestBody:
 150       required: true
 151       content:
 152         '*/*':
 153           schema:
 154             type: object
 155           examples:
 156             dataSampleRequest:
 157               $ref: 'components.yaml#/components/examples/dataSamplePatchRequest'
 158     responses:
 159       200:
 160         $ref: 'components.yaml#/components/responses/Ok'
 161       400:
 162         $ref: 'components.yaml#/components/responses/BadRequest'
 163       403:
 164         $ref: 'components.yaml#/components/responses/Forbidden'
 165       409:
 166         $ref: 'components.yaml#/components/responses/Conflict'
 167       500:
 168         $ref: 'components.yaml#/components/responses/InternalServerError'
 169       502:
 170         $ref: 'components.yaml#/components/responses/BadGateway'
 171
 172   delete:
 173     tags:
 174       - network-cm-proxy
 175     summary: Delete resource data
 176     description: Delete resource data from pass-through running for a given cm handle
 177     operationId: deleteResourceDataRunningForCmHandle
 178     parameters:
 179       - $ref: 'components.yaml#/components/parameters/datastoreName'
 180       - $ref: 'components.yaml#/components/parameters/cmHandleReferenceInPath'
 181       - $ref: 'components.yaml#/components/parameters/resourceIdentifierInQuery'
 182       - $ref: 'components.yaml#/components/parameters/contentParamInHeader'
 183       - $ref: 'components.yaml#/components/parameters/authorizationParamInHeader'
 184     responses:
 185       204:
 186         $ref: 'components.yaml#/components/responses/NoContent'
 187       400:
 188         $ref: 'components.yaml#/components/responses/BadRequest'
 189       403:
 190         $ref: 'components.yaml#/components/responses/Forbidden'
 191       404:
 192         $ref: 'components.yaml#/components/responses/NotFound'
 193       409:
 194         $ref: 'components.yaml#/components/responses/Conflict'
 195       500:
 196         $ref: 'components.yaml#/components/responses/InternalServerError'
 197       502:
 198         $ref: 'components.yaml#/components/responses/BadGateway'
 199
 200 dataOperationForCmHandle:
 201   post:
 202     tags:
 203       - network-cm-proxy
 204     summary: Execute a data operation for group of cm handle references
 205     description: This request will be handled asynchronously using messaging to the supplied topic. The rest response will be an acknowledge with a requestId to identify the relevant messages. A maximum of 200 cm handles per operation is supported.
 206     operationId: executeDataOperationForCmHandles
 207     parameters:
 208       - $ref: 'components.yaml#/components/parameters/requiredTopicParamInQuery'
 209       - $ref: 'components.yaml#/components/parameters/authorizationParamInHeader'
 210     requestBody:
 211       required: true
 212       content:
 213         application/json:
 214           schema:
 215             $ref: 'components.yaml#/components/schemas/DataOperationRequest'
 216     responses:
 217       200:
 218         description: OK
 219         content:
 220           application/json:
 221             schema:
 222               type: object
 223       400:
 224         $ref: 'components.yaml#/components/responses/BadRequest'
 225       403:
 226         $ref: 'components.yaml#/components/responses/Forbidden'
 227       413:
 228         $ref: 'components.yaml#/components/responses/PayloadTooLarge'
 229       500:
 230         $ref: 'components.yaml#/components/responses/InternalServerError'
 231       502:
 232         $ref: 'components.yaml#/components/responses/BadGateway'
 233
 234 queryResourceDataForCmHandle:
 235   get:
 236     tags:
 237       - network-cm-proxy
 238     summary: Query resource data for a given cm handle
 239     description: Query resource data for a given cm handle
 240     operationId: queryResourceDataForCmHandle
 241     parameters:
 242       - $ref: 'components.yaml#/components/parameters/datastoreName'
 243       - $ref: 'components.yaml#/components/parameters/cmHandleInPath'
 244       - $ref: 'components.yaml#/components/parameters/cpsPathInQuery'
 245       - $ref: 'components.yaml#/components/parameters/optionsParamInQuery'
 246       - $ref: 'components.yaml#/components/parameters/topicParamInQuery'
 247       - $ref: 'components.yaml#/components/parameters/includeDescendantsOptionInQuery'
 248     responses:
 249       200:
 250         description: OK
 251         content:
 252           application/json:
 253             schema:
 254               type: object
 255             examples:
 256               dataSampleResponse:
 257                 $ref: 'components.yaml#/components/examples/dataSampleResponse'
 258       400:
 259         $ref: 'components.yaml#/components/responses/BadRequest'
 260       403:
 261         $ref: 'components.yaml#/components/responses/Forbidden'
 262       500:
 263         $ref: 'components.yaml#/components/responses/InternalServerError'
 264       502:
 265         $ref: 'components.yaml#/components/responses/BadGateway'
 266
 267 fetchModuleReferencesByCmHandle:
 268   get:
 269     description: fetch all module references (name and revision) for a given cm handle
 270     tags:
 271       - network-cm-proxy
 272     summary: Fetch all module references (name and revision) for a given cm handle
 273     operationId: getModuleReferencesByCmHandle
 274     parameters:
 275       - $ref: 'components.yaml#/components/parameters/cmHandleReferenceInPath'
 276     responses:
 277       200:
 278         description: OK
 279         content:
 280           application/json:
 281             schema:
 282               type: array
 283               items:
 284                 $ref: 'components.yaml#/components/schemas/RestModuleReference'
 285       400:
 286         $ref: 'components.yaml#/components/responses/BadRequest'
 287       403:
 288         $ref: 'components.yaml#/components/responses/Forbidden'
 289       500:
 290         $ref: 'components.yaml#/components/responses/InternalServerError'
 291
 292 getModuleDefinitions:
 293   get:
 294     tags:
 295       - network-cm-proxy
 296     summary: Get module definitions
 297     description: Get module definitions (module name, revision, yang resource) with options to filter on module name and revision
 298     operationId: getModuleDefinitions
 299     parameters:
 300       - $ref: 'components.yaml#/components/parameters/cmHandleReferenceInPath'
 301       - $ref: 'components.yaml#/components/parameters/moduleNameInQuery'
 302       - $ref: 'components.yaml#/components/parameters/revisionInQuery'
 303     responses:
 304       200:
 305         description: OK
 306         content:
 307           application/json:
 308             schema:
 309               type: array
 310               items:
 311                 $ref: 'components.yaml#/components/schemas/RestModuleDefinition'
 312       403:
 313         $ref: 'components.yaml#/components/responses/Forbidden'
 314       500:
 315         $ref: 'components.yaml#/components/responses/InternalServerError'
 316
 317 searchCmHandles:
 318   post:
 319     description: Execute cm handle query search and return a list of cm handle details. Any number of conditions can be applied. To be included in the result a cm-handle must fulfill ALL the conditions. An empty collection will be returned in the case that the cm handle does not match a condition. For more on cm handle query search please refer to <a href="https://docs.onap.org/projects/onap-cps/en/latest/ncmp-cmhandle-querying.html">cm handle query search Read the Docs</a>.<br/>By supplying a CPS Path it is possible to query on any data related to the cm handle. For more on CPS Path please refer to <a href="https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html">CPS Path Read the Docs</a>. The cm handle ancestor is automatically returned for this query.
 320     tags:
 321       - network-cm-proxy
 322     summary: Execute cm handle search using the available conditions
 323     operationId: searchCmHandles
 324     requestBody:
 325       required: true
 326       content:
 327         application/json:
 328           schema:
 329             $ref: 'components.yaml#/components/schemas/CmHandleQueryParameters'
 330           examples:
 331             Cm handle properties query:
 332               $ref: 'components.yaml#/components/examples/pubPropCmHandleQueryParameters'
 333             Cm handle modules query:
 334               $ref: 'components.yaml#/components/examples/modulesCmHandleQueryParameters'
 335             All cm handle query parameters:
 336               $ref: 'components.yaml#/components/examples/allCmHandleQueryParameters'
 337             Cm handle with CPS path state query:
 338               $ref: 'components.yaml#/components/examples/cpsPathCmHandleStateQueryParameters'
 339             Cm handle with data sync flag query:
 340               $ref: 'components.yaml#/components/examples/cpsPathCmHandleDataSyncQueryParameters'
 341     responses:
 342       200:
 343         description: OK
 344         content:
 345           application/json:
 346             schema:
 347               type: array
 348               items:
 349                 $ref: 'components.yaml#/components/schemas/RestOutputCmHandle'
 350       400:
 351         $ref: 'components.yaml#/components/responses/BadRequest'
 352       403:
 353         $ref: 'components.yaml#/components/responses/Forbidden'
 354       500:
 355         $ref: 'components.yaml#/components/responses/InternalServerError'
 356
 357 retrieveCmHandleDetailsById:
 358   get:
 359     description: Retrieve CM handle details and properties by cm handle id
 360     tags:
 361       - network-cm-proxy
 362     summary: Retrieve CM handle details
 363     operationId: retrieveCmHandleDetailsById
 364     parameters:
 365       - $ref: 'components.yaml#/components/parameters/cmHandleReferenceInPath'
 366     responses:
 367       200:
 368         description: OK
 369         content:
 370           application/json:
 371             schema:
 372               $ref: 'components.yaml#/components/schemas/RestOutputCmHandle'
 373       400:
 374         $ref: 'components.yaml#/components/responses/BadRequest'
 375       404:
 376         $ref: 'components.yaml#/components/responses/NotFound'
 377       500:
 378         $ref: 'components.yaml#/components/responses/InternalServerError'
 379
 380 getCmHandlePropertiesById:
 381   get:
 382     description: Get CM handle properties by cm handle id
 383     tags:
 384       - network-cm-proxy
 385     summary: Get CM handle properties
 386     operationId: getPublicCmHandlePropertiesByCmHandleId
 387     parameters:
 388       - $ref: 'components.yaml#/components/parameters/cmHandleReferenceInPath'
 389     responses:
 390       200:
 391         description: OK
 392         content:
 393           application/json:
 394             schema:
 395               $ref: 'components.yaml#/components/schemas/RestOutputPublicCmHandleProperties'
 396       400:
 397         $ref: 'components.yaml#/components/responses/BadRequest'
 398       404:
 399         $ref: 'components.yaml#/components/responses/NotFound'
 400       500:
 401         $ref: 'components.yaml#/components/responses/InternalServerError'
 402
 403 getCmHandleStateById:
 404   get:
 405     description: Get CM handle state by cm handle id
 406     tags:
 407       - network-cm-proxy
 408     summary: Get CM handle state
 409     operationId: getCmHandleStateByCmHandleId
 410     parameters:
 411       - $ref: 'components.yaml#/components/parameters/cmHandleReferenceInPath'
 412     responses:
 413       200:
 414         description: OK
 415         content:
 416           application/json:
 417             schema:
 418               $ref: 'components.yaml#/components/schemas/RestOutputCmHandleCompositeState'
 419       400:
 420         $ref: 'components.yaml#/components/responses/BadRequest'
 421       404:
 422         $ref: 'components.yaml#/components/responses/NotFound'
 423       500:
 424         $ref: 'components.yaml#/components/responses/InternalServerError'
 425
 426 searchCmHandleIds:
 427   post:
 428     description: Execute cm handle query search and return a list of cm handle references. Any number of conditions can be applied. To be included in the result a cm handle must fulfill ALL the conditions. An empty collection will be returned in the case that the cm handle does not match a condition. For more on cm handle query search please refer to <a href="https://docs.onap.org/projects/onap-cps/en/latest/ncmp-cmhandle-querying.html">cm handle query search Read the Docs</a>.<br/>By supplying a CPS Path it is possible to query on any data related to the cm handle. For more on CPS Path please refer to <a href="https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html">CPS Path Read the Docs</a>. The cm handle ancestor is automatically returned for this query.
 429     tags:
 430       - network-cm-proxy
 431     summary: Execute cm handle query upon a given set of query parameters
 432     operationId: searchCmHandleIds
 433     parameters:
 434       - $ref: 'components.yaml#/components/parameters/outputAlternateIdOptionInQuery'
 435     requestBody:
 436       required: true
 437       content:
 438         application/json:
 439           schema:
 440             $ref: 'components.yaml#/components/schemas/CmHandleQueryParameters'
 441           examples:
 442             Cm handle properties query:
 443               $ref: 'components.yaml#/components/examples/pubPropCmHandleQueryParameters'
 444             Cm handle modules query:
 445               $ref: 'components.yaml#/components/examples/modulesCmHandleQueryParameters'
 446             All cm handle query parameters:
 447               $ref: 'components.yaml#/components/examples/allCmHandleQueryParameters'
 448             Cm handle with CPS path state query:
 449               $ref: 'components.yaml#/components/examples/cpsPathCmHandleStateQueryParameters'
 450             Cm handle with data sync flag query:
 451               $ref: 'components.yaml#/components/examples/cpsPathCmHandleDataSyncQueryParameters'
 452     responses:
 453       200:
 454         description: OK
 455         content:
 456           application/json:
 457             schema:
 458               type: array
 459               items:
 460                 type: string
 461       400:
 462         $ref: 'components.yaml#/components/responses/BadRequest'
 463       403:
 464         $ref: 'components.yaml#/components/responses/Forbidden'
 465       404:
 466         $ref: 'components.yaml#/components/responses/NotFound'
 467       500:
 468         $ref: 'components.yaml#/components/responses/InternalServerError'
 469
 470 setDataSyncEnabledFlag:
 471   put:
 472     tags:
 473       - network-cm-proxy
 474     summary: Set the Data Sync Enabled Flag
 475     description: Set the data sync enabled flag to true or false for a specified Cm-Handle. This will in turn set the data sync state to UNSYNCHRONIZED and NONE_REQUESTED respectfully.
 476     operationId: setDataSyncEnabledFlagForCmHandle
 477     parameters:
 478       - $ref: 'components.yaml#/components/parameters/cmHandleInPath'
 479       - $ref: 'components.yaml#/components/parameters/dataSyncEnabled'
 480     responses:
 481       200:
 482         $ref: 'components.yaml#/components/responses/Ok'
 483       400:
 484         $ref: 'components.yaml#/components/responses/BadRequest'
 485       403:
 486         $ref: 'components.yaml#/components/responses/Forbidden'
 487       500:
 488         $ref: 'components.yaml#/components/responses/InternalServerError'
 489       502:
 490         $ref: 'components.yaml#/components/responses/BadGateway'