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