docs/offeredapis/api_serviceCatalog/swagger.yaml

   1 #    Copyright (c) 2018 Orange
   2 #
   3 #    Licensed under the Apache License, Version 2.0 (the "License");
   4 #    you may not use this file except in compliance with the License.
   5 #    You may obtain a copy of the License at
   6 #
   7 #        http://www.apache.org/licenses/LICENSE-2.0
   8 #
   9 #    Unless required by applicable law or agreed to in writing, software
  10 #    distributed under the License is distributed on an "AS IS" BASIS,
  11 #    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 #    See the License for the specific language governing permissions and
  13 #    limitations under the License.swagger: "2.0"
  14 swagger: "2.0"
  15 info:
  16   description: "ServiceCatalog API to retrieve Service Specifications that are available from ONAP.\nThis API is\
  17     \ build from TMF open API17.5. \nOnly operation GET (by id & byList) for resource\
  18     \ serviceSpecification is available\n \
  19     \ To view this swagger file import it into https://editor.swagger.io/ \n"
  20   version: "4.0.1"
  21   title: "ServiceCatalog API"
  22   contact:
  23     name: "ONAP"
  24     url: "https://onap.readthedocs.io"
  25     email: "onap-discuss@lists.onap.org"
  26   license:
  27     name: "Apache 2.0"
  28     url: "http://www.apache.org/licenses/LICENSE-2.0"
  29   x-planned-retirement-date: "205001"
  30   x-component: "NBI"
  31   x-logo:
  32     url: "/redoc/logo.png"
  33     backgroundColor: "#FFFFFF"
  34 host: "serverRoot:30274"
  35 basePath: "/nbi/api/v4"
  36 schemes:
  37 - "http"
  38 produces:
  39 - "application/json;charset=utf-8"
  40 tags:
  41 - name: "ServiceSpecification"
  42   description: ""
  43 paths:
  44   /serviceSpecification:
  45     get:
  46       tags:
  47       - "ServiceSpecification"
  48       produces:
  49       - "application/json;charset=utf-8"
  50       operationId: "serviceSpecification_Find"
  51       summary: "List service specifications"
  52       description: "This operation returns service specifications from a catalog.\n\
  53         Only a predefined set of attribute is proposed : Based on SDC limitations,\
  54         \ only attributes category and distributionStatus are available for serviceSpecification\
  55         \ filtering\nFields attribute could be used to filter attributes retrieved"
  56       deprecated: false
  57       parameters:
  58       - name: "fields"
  59         required: false
  60         in: "query"
  61         description: "Field selection - used to filtering the attributes to be retreived"
  62         type: "string"
  63       - name: "category"
  64         required: false
  65         in: "query"
  66         description: "Service Category (filter)"
  67         type: "string"
  68       - name: "distributionStatus"
  69         required: false
  70         in: "query"
  71         description: "Service distribution status (filter)"
  72         type: "string"
  73       responses:
  74         200:
  75           description: "Ok"
  76           schema:
  77             type: "array"
  78             items:
  79               $ref: "#/definitions/ServiceSpecification"
  80         400:
  81           description: "Bad Request\n\nList of supported error codes:\n- 20: Invalid\
  82             \ URL parameter value\n- 21: Missing body\n- 22: Invalid body\n- 23: Missing\
  83             \ body field\n- 24: Invalid body field\n- 25: Missing header\n- 26: Invalid\
  84             \ header value\n- 27: Missing query-string parameter\n- 28: Invalid query-string\
  85             \ parameter value"
  86           schema:
  87             $ref: "#/definitions/ErrorRepresentation"
  88         401:
  89           description: "Unauthorized\n\nList of supported error codes:\n- 40: Missing\
  90             \ credentials\n- 41: Invalid credentials\n- 42: Expired credentials"
  91           schema:
  92             $ref: "#/definitions/ErrorRepresentation"
  93         403:
  94           description: "Forbidden\n\nList of supported error codes:\n- 50: Access\
  95             \ denied\n- 51: Forbidden requester\n- 52: Forbidden user\n- 53: Too many\
  96             \ requests"
  97           schema:
  98             $ref: "#/definitions/ErrorRepresentation"
  99         404:
 100           description: "Not Found\n\nList of supported error codes:\n- 60: Resource\
 101             \ not found"
 102           schema:
 103             $ref: "#/definitions/ErrorRepresentation"
 104         422:
 105           description: "Unprocessable entity\n\nFunctional error"
 106           schema:
 107             $ref: "#/definitions/ErrorRepresentation"
 108         500:
 109           description: "Internal Server Error\n\nList of supported error codes:\n\
 110             - 1: Internal error"
 111           schema:
 112             $ref: "#/definitions/ErrorRepresentation"
 113         503:
 114           description: "Service Unavailable\n\nList of supported error codes:\n- 5:\
 115             \ The service is temporarily unavailable\n- 6: Orange API is over capacity,\
 116             \ retry later !"
 117           schema:
 118             $ref: "#/definitions/ErrorRepresentation"
 119   /serviceSpecification/{id}:
 120     get:
 121       tags:
 122       - "ServiceSpecification"
 123       produces:
 124       - "application/json;charset=utf-8"
 125       operationId: "serviceSpecification_Get"
 126       summary: "Retrieve a service specification"
 127       description: "This operation returns a service specification by its id from\
 128         \ a catalog. Attribute selection is enabled using the fields attribute."
 129       deprecated: false
 130       parameters:
 131       - name: "id"
 132         required: true
 133         in: "path"
 134         type: "string"
 135       - name: "fields"
 136         required: false
 137         in: "query"
 138         description: "Attribute selection"
 139         type: "string"
 140       responses:
 141         200:
 142           description: "Ok"
 143           schema:
 144             $ref: "#/definitions/ServiceSpecification"
 145         400:
 146           description: "Bad Request\n\nList of supported error codes:\n- 20: Invalid\
 147             \ URL parameter value\n- 21: Missing body\n- 22: Invalid body\n- 23: Missing\
 148             \ body field\n- 24: Invalid body field\n- 25: Missing header\n- 26: Invalid\
 149             \ header value\n- 27: Missing query-string parameter\n- 28: Invalid query-string\
 150             \ parameter value"
 151           schema:
 152             $ref: "#/definitions/ErrorRepresentation"
 153         401:
 154           description: "Unauthorized\n\nList of supported error codes:\n- 40: Missing\
 155             \ credentials\n- 41: Invalid credentials\n- 42: Expired credentials"
 156           schema:
 157             $ref: "#/definitions/ErrorRepresentation"
 158         403:
 159           description: "Forbidden\n\nList of supported error codes:\n- 50: Access\
 160             \ denied\n- 51: Forbidden requester\n- 52: Forbidden user\n- 53: Too many\
 161             \ requests"
 162           schema:
 163             $ref: "#/definitions/ErrorRepresentation"
 164         404:
 165           description: "Not Found\n\nList of supported error codes:\n- 60: Resource\
 166             \ not found"
 167           schema:
 168             $ref: "#/definitions/ErrorRepresentation"
 169         422:
 170           description: "Unprocessable entity\n\nFunctional error"
 171           schema:
 172             $ref: "#/definitions/ErrorRepresentation"
 173         500:
 174           description: "Internal Server Error\n\nList of supported error codes:\n\
 175             - 1: Internal error"
 176           schema:
 177             $ref: "#/definitions/ErrorRepresentation"
 178         503:
 179           description: "Service Unavailable\n\nList of supported error codes:\n- 5:\
 180             \ The service is temporarily unavailable\n- 6: Orange API is over capacity,\
 181             \ retry later !"
 182           schema:
 183             $ref: "#/definitions/ErrorRepresentation"
 184   /serviceSpecification/{id}/specificationInputSchema:
 185     get:
 186       tags:
 187       - "ServiceSpecification"
 188       produces:
 189       - "application/json;charset=utf-8"
 190       operationId: "specificationInputSchemaGet"
 191       summary: "Retrieve a service specification Input Schema"
 192       description: "This operation returns a service specification Input schema by its id from\
 193         \ a catalog. Attribute selection is enabled using the fields attribute."
 194       deprecated: false
 195       parameters:
 196       - name: "id"
 197         required: true
 198         in: "path"
 199         type: "string"
 200       - name: "fields"
 201         required: false
 202         in: "query"
 203         description: "Attribute selection"
 204         type: "string"
 205       responses:
 206         200:
 207           description: "Ok"
 208           schema:
 209             $ref: "#/definitions/SpecificationInputSchema"
 210         400:
 211           description: "Bad Request\n\nList of supported error codes:\n- 20: Invalid\
 212             \ URL parameter value\n- 21: Missing body\n- 22: Invalid body\n- 23: Missing\
 213             \ body field\n- 24: Invalid body field\n- 25: Missing header\n- 26: Invalid\
 214             \ header value\n- 27: Missing query-string parameter\n- 28: Invalid query-string\
 215             \ parameter value"
 216           schema:
 217             $ref: "#/definitions/ErrorRepresentation"
 218         401:
 219           description: "Unauthorized\n\nList of supported error codes:\n- 40: Missing\
 220             \ credentials\n- 41: Invalid credentials\n- 42: Expired credentials"
 221           schema:
 222             $ref: "#/definitions/ErrorRepresentation"
 223         403:
 224           description: "Forbidden\n\nList of supported error codes:\n- 50: Access\
 225             \ denied\n- 51: Forbidden requester\n- 52: Forbidden user\n- 53: Too many\
 226             \ requests"
 227           schema:
 228             $ref: "#/definitions/ErrorRepresentation"
 229         404:
 230           description: "Not Found\n\nList of supported error codes:\n- 60: Resource\
 231             \ not found"
 232           schema:
 233             $ref: "#/definitions/ErrorRepresentation"
 234         422:
 235           description: "Unprocessable entity\n\nFunctional error"
 236           schema:
 237             $ref: "#/definitions/ErrorRepresentation"
 238         500:
 239           description: "Internal Server Error\n\nList of supported error codes:\n\
 240             - 1: Internal error"
 241           schema:
 242             $ref: "#/definitions/ErrorRepresentation"
 243         503:
 244           description: "Service Unavailable\n\nList of supported error codes:\n- 5:\
 245             \ The service is temporarily unavailable\n- 6: Orange API is over capacity,\
 246             \ retry later !"
 247           schema:
 248             $ref: "#/definitions/ErrorRepresentation"
 249
 250 definitions:
 251   LifecycleStatusValues:
 252     description: "Service lifecycle value from ONAP SDC"
 253     type: "string"
 254     enum:
 255     - "NOT_CERTIFIED_CHECKOUT"
 256     - "NOT_CERTIFIED_CHECKIN"
 257     - "READY_FOR_CERTIFICATION"
 258     - "CERTIFICATION_IN_PROGRESS"
 259     - "CERTIFIED"
 260   DistributionStatus:
 261     description: "Service distribution status from ONAP."
 262     type: "string"
 263     enum:
 264     - "DISTRIBUTION_NOT_APPROVED"
 265     - "DISTRIBUTION_APPROVED"
 266     - "DISTRIBUTED"
 267     - "DISTRIBUTION_REJECTED"
 268   ErrorRepresentation:
 269     description: "This class is used to describe error.\nfor nbi Beijing release we\
 270       \ do not manage additional error for serviceCatalog"
 271     required:
 272     - "code"
 273     - "reason"
 274     type: "object"
 275     properties:
 276       code:
 277         description: "Application related code (as defined in the API or from a common\
 278           \ list)"
 279         type: "integer"
 280         format: "int32"
 281       reason:
 282         description: "Text that explains the reason for error. This can be shown to\
 283           \ a client user."
 284         type: "string"
 285       message:
 286         description: "Text that provide more details and corrective actions related\
 287           \ to the error. This can be shown to a client user"
 288         type: "string"
 289       status:
 290         description: "http error code extension like 400-2"
 291         type: "string"
 292       referenceErrror:
 293         description: "url pointing to documentation describing the error"
 294         type: "string"
 295       '@type':
 296         description: "The class type of a REST resource."
 297         type: "string"
 298       '@schemaLocation':
 299         description: "it provides a link to the schema describing a REST resource."
 300         type: "string"
 301   TimePeriod:
 302     description: "A time period"
 303     type: "object"
 304     properties:
 305       startDateTime:
 306         description: "Start date and time of the period"
 307         type: "string"
 308         format: "date-time"
 309       endDateTime:
 310         description: "End date and time of the period"
 311         type: "string"
 312         format: "date-time"
 313   RelatedPartyRef:
 314     description: "Party linked to the service catalog.\nin nbi we retrieve information\
 315       \ about last updater of the service in SDC"
 316     type: "object"
 317     properties:
 318       id:
 319         description: "Unique identifier of the related party. Filled with lastUpdaterUserId"
 320         type: "string"
 321       role:
 322         description: "Role payed by the related party\nOnly role 'lastUpdater' is\
 323           \ retrieved in Beijing release"
 324         type: "string"
 325       name:
 326         description: "Name of the related party - Filled with lastUpdatedFullName"
 327         type: "string"
 328   ServiceSpecification:
 329     description: "ServiceSpecification is a class that offers characteristics to describe\
 330       \ a type of service. Functionally, it acts as a template by which Services may\
 331       \ be instantiated. By sharing the same specification, these services would therefore\
 332       \ share the same set of characteristics.\nthe service information are retrieved\
 333       \ in SDC"
 334     required:
 335     - "invariantUUID"
 336     type: "object"
 337     properties:
 338       id:
 339         description: "Unique identifier of the service specification. Filled with\
 340           \ SDC Service uuid"
 341         type: "string"
 342       href:
 343         description: "Reference of the service specification"
 344         type: "string"
 345       name:
 346         description: "Name of the service specification- Filled with SDC Service name"
 347         type: "string"
 348       description:
 349         description: "A narrative that explains in detail what the service specification\
 350           \ is - Filled with SDC Service description"
 351         type: "string"
 352       '@type':
 353         description: "This attribute allows to dynamically extends TMF class. Valued\
 354           \ with 'ONAPservice'. We used this features to add following attributes:\n\
 355           invariantUUID\ntoscaModelURL\ntoscaResourceName\ncategory (1)\nsubcategory\
 356           \ (1)\ndistributionStatus"
 357         type: "string"
 358         default: "ONAPservice"
 359       '@schemaLocation':
 360         description: "Not used"
 361         type: "string"
 362       '@baseType':
 363         description: "Not used"
 364         type: "string"
 365       invariantUUID:
 366         description: "Additional attribute (not in the TMF API) - extended through\
 367           \ @type - invariantUUID"
 368         type: "string"
 369       toscaModelURL:
 370         description: "Additional attribute (not in the TMF API) - extended through\
 371           \ @type - toscaModelURL"
 372         type: "string"
 373       toscaResourceName:
 374         description: "Additional attribute (not in the TMF API) - extended through\
 375           \ @type - toscaResourceName"
 376         type: "string"
 377       category:
 378         description: "Additional attribute - extended through @type - category\nPlease\
 379           \ note that this attribute is managed in TMF - in future release we'll introduce\
 380           \ category resource"
 381         type: "string"
 382       subcategory:
 383         description: "Additional attribute - extended through @type - category\nPlease\
 384           \ note that this attribute is managed in TMF - in future release we'll introduce\
 385           \ category resourc"
 386         type: "string"
 387       distributionStatus:
 388         $ref: "#/definitions/DistributionStatus"
 389       version:
 390         description: "Service specification version - Filled with SDC Service version"
 391         type: "string"
 392       lifecycleStatus:
 393         $ref: "#/definitions/LifecycleStatusValues"
 394       targetServiceSchema:
 395         $ref: "#/definitions/TargetServiceSchemaRef"
 396       attachment:
 397         type: "array"
 398         items:
 399           $ref: "#/definitions/Attachment"
 400       relatedParty:
 401         type: "array"
 402         items:
 403           $ref: "#/definitions/RelatedPartyRef"
 404       resourceSpecification:
 405         type: "array"
 406         items:
 407           $ref: "#/definitions/ResourceSpecificationRef"
 408       serviceSpecCharacteristic:
 409         type: "array"
 410         items:
 411           $ref: "#/definitions/ServiceSpecCharacteristic"
 412   ServiceSpecCharacteristic:
 413     description: "A characteristic quality or distinctive feature of a ServiceSpecification.\
 414       \ \nServiceSpecCharacteristic are retrieved in the serviceTosca file in the\
 415       \ topology_template section in the inputs section."
 416     type: "object"
 417     properties:
 418       name:
 419         description: "Name of the characteristic - Filled with parameter_name"
 420         type: "string"
 421       description:
 422         description: "A narrative that explains in detail what the characteristic\
 423           \ is - Filled with parameter_description"
 424         type: "string"
 425       valueType:
 426         description: "A kind of value that the characteristic can take on, from Dublin\
 427           \ from Dublin we use the object type to describe service characteristic values"
 428         type: "string"
 429       '@type':
 430         description: "This attribute allows to dynamically extends TMF class. Valued\
 431           \ with: 'ONAPserviceCharacteristic'. We do not used this feature in nbi"
 432         type: "string"
 433       '@schemaLocation':
 434         description: "An url pointing to type description - we do not use it"
 435         type: "string"
 436       required:
 437         description: "A parameter to define if the characteristic is mandatory - Filled\
 438           \ from parameter_required – if not fielded by default ‘true’"
 439         type: "boolean"
 440         default: true
 441       status:
 442         description: "Status of the characteristic - filled with status_value"
 443         type: "string"
 444       serviceSpecCharacteristicValue:
 445         type: "array"
 446         items:
 447           $ref: "#/definitions/ServiceSpecCharacteristicValue"
 448   Attachment:
 449     description: "An attachment is a file uses to describe the service.\nIn nbi we\
 450       \ use attachment to retrieve ONAP artifacts."
 451     type: "object"
 452     properties:
 453       id:
 454         description: "Unique identifier of the attachment - filled with artifactUUID."
 455         type: "string"
 456       name:
 457         description: "Name of the attachment - filled with artifactName"
 458         type: "string"
 459       description:
 460         description: "Description of the attachment - filled with artifactDescription"
 461         type: "string"
 462       '@type':
 463         description: "This attribute allows to dynamically extends TMF class. Valued\
 464           \ with 'ONAPartifact'. We used this features to add following attributes:\
 465           \ \nartifactLabel\nartifactGroupType\nartifactTimeout\nartifactChecksum\n\
 466           artifactVersion\ngeneratedFromUUID"
 467         type: "string"
 468         default: "ONAPartifact"
 469       artifactLabel:
 470         description: "Additional attribute (not in the TMF API) - extended through\
 471           \ @type - artifactLabel"
 472         type: "string"
 473       artifactGroupType:
 474         description: "Additional attribute (not in the TMF API) - extended through\
 475           \ @type - artifactGroupType"
 476         type: "string"
 477       artifactTimeout:
 478         description: "Additional attribute (not in the TMF API) - extended through\
 479           \ @type - artifactTimeout"
 480         type: "string"
 481       artifactChecksum:
 482         description: "Additional attribute (not in the TMF API) - extended through\
 483           \ @type - artifactChecksum"
 484         type: "string"
 485       artifactVersion:
 486         description: "Additional attribute (not in the TMF API) - extended through\
 487           \ @type - artifactVersion"
 488         type: "string"
 489       generatedFromUUID:
 490         description: "Additional attribute (not in the TMF API) - extended through\
 491           \ @type - generatedFromUUID"
 492         type: "string"
 493       url:
 494         description: "Uniform Resource Locator, is a web page address - filled with\
 495           \ artifactURL"
 496         type: "string"
 497       mimeType:
 498         description: "Filled with artifactType"
 499         type: "string"
 500   ServiceSpecCharacteristicValue:
 501     description: "A number or text that can be assigned to a service specification\
 502       \ characteristic.\nServiceSpecCharacteristicValue are retrieved in the service\
 503       \ Tosca file"
 504     type: "object"
 505     properties:
 506       '@type':
 507         description: "This attribute allows to dynamically extends TMF class. Valued\
 508           \ with: 'ServiceSpecName_ServiceCharacteristic'."
 509         type: "string"
 510       '@schemaLocation':
 511         description: "An url pointing to type description - we use it in nbi\
 512           \ for specifying the specificationInputSchema url"
 513         type: "string"
 514       valueType:
 515         description: "A kind of value that the characteristic can take on,\
 516           \ from Dublin release we use an object valueType to\
 517           \ group the Tosca Model Inputs, the object schema is described\
 518           \ by the specificationInputSchema url"
 519         type: "string"
 520   SpecificationInputSchema:
 521     description: "A json schema of the service specification input characteristics\
 522       \ \n. The Inputs in the schema files are obtained the service Tosca file Inputs"
 523     type: "object"
 524     properties:
 525       ServiceCharacteristics:
 526         $ref: "#/definitions/SchemaForServiceCharacteristics"
 527   SchemaForServiceCharacteristics:
 528     description: "The object describing the schema of the service specification input characteristics.\
 529       \ \n. The Inputs in the schema files are obtained the service Tosca file Inputs"
 530     type: "object"
 531     properties:
 532       required:
 533         description: "defines the parameter key names that are mandatory to send"
 534         type: "array"
 535         items:
 536           type: "string"
 537       properties:
 538         description: "defines all the input key names and types for the Service Instantiation"
 539         type: "object"
 540   ResourceSpecificationRef:
 541     description: "A list of resourceSpec identified to deliver the service.\nfor nbi\
 542       \ we retrieve resource information available in service description (through\
 543       \ SDC api) bu as well information retrieved in the TOSCA file."
 544     type: "object"
 545     properties:
 546       id:
 547         description: "Unique identifier of the resource specification - filled with\
 548           \ resourceUUID"
 549         type: "string"
 550       version:
 551         description: "Version for this resource specification - filled with resourceVersion"
 552         type: "string"
 553       name:
 554         description: "Name of the resource specification - filled with resourceName"
 555         type: "string"
 556       '@type':
 557         description: "This attribute allows to dynamically extends TMF class. Valued\
 558           \ with: 'ONAPresource'. We used this features to add following attributes:\n\
 559           resourceInstanceName\nresourceInvariantUUID\nresourceType\nmodelCustomizationName\n\
 560           modelCustomizationId"
 561         type: "string"
 562         default: "ONAPresource"
 563       resourceInstanceName:
 564         description: "Additional attribute (not in the TMF API) - extended through\
 565           \ @type - resourceInstanceName"
 566         type: "string"
 567       resourceInvariantUUID:
 568         description: "Additional attribute (not in the TMF API) - extended through\
 569           \ @type - resourceInvariantUUID"
 570         type: "string"
 571       resourceType:
 572         description: "Additional attribute (not in the TMF API) - extended through\
 573           \ @type - resoucreType"
 574         type: "string"
 575       modelCustomizationName:
 576         description: "Additional attribute (not in the TMF API) - extended through\
 577           \ @type - Retrieved in the TOSCA file : attribute name in topology_template/node_template\
 578           \ for the resource"
 579         type: "string"
 580       modelCustomizationId:
 581         description: "Additional attribute (not in the TMF API) - extended through\
 582           \ @type - Retrieved in the TOSCA file : attribute customizationUUID in topology_template/node_template\
 583           \ for the resource"
 584         type: "string"
 585   TargetServiceSchemaRef:
 586     description: ""
 587     required:
 588     - "@type"
 589     - "@schemaLocation"
 590     type: "object"
 591     properties:
 592       '@type':
 593         description: ""
 594         type: "string"
 595       '@schemaLocation':
 596         description: ""
 597         type: "string"