docs/offeredapis/serviceCatalog/asciiDoc.adoc

   1 ////
   2 This work is licensed under a Creative Commons Attribution 4.0 International License.
   3 http://creativecommons.org/licenses/by/4.0
   4 Copyright 2018 Orange
   5 ////
   6
   7 = API ServiceCatalog
   8
   9
  10 [[_overview]]
  11 == Overview
  12
  13 === Api URL
  14
  15 https://api-designer.sso.infra.ftgroup/swagger-ui/?url=https://api-designer.sso.infra.ftgroup/api/1.0/apis/N3ma89X1x0/swagger.json[Swagger UI]
  16
  17
  18 https://plantuml.rd.francetelecom.fr/proxy?fmt=svg&src=https://api-designer.sso.infra.ftgroup/api/1.0/apis/N3ma89X1x0/plantuml&noCache=797767.0[plant UML UI]
  19
  20 serviceCatalog API designed for ONAP Beijing Release.
  21 This API is build from TMF open API17.5.
  22 Only operation GET (by id &amp; byList) for resource serviceSpecification is available
  23
  24
  25 === Version information
  26 [%hardbreaks]
  27 __Version__ : 1.0.0_inProgress
  28
  29
  30 === URI scheme
  31 [%hardbreaks]
  32 __Host__ : serverRoot
  33 __BasePath__ : /nbi/api/v1
  34 __Schemes__ : HTTPS
  35
  36
  37 === Tags
  38
  39 * ServiceSpecification
  40
  41
  42 === Consumes
  43
  44 * `application/json;charset=utf-8`
  45
  46
  47 === Produces
  48
  49 * `application/json;charset=utf-8`
  50
  51
  52 [[_paths]]
  53 == Resources
  54
  55 [[_servicespecification_resource]]
  56 === ServiceSpecification
  57
  58 [[_servicespecificationfind]]
  59 ==== List service specifications
  60 ....
  61 GET /serviceSpecification
  62 ....
  63
  64
  65 ===== Description
  66 This operation returns service specifications from a catalog.
  67 Only a predefined set of attribute is proposed : Based on SDC limitations, only attributes category and distributionStatus are available for serviceSpecification filtering
  68 Fields attribute could be used to filter attributes retrieved
  69
  70 Specific business errors for current operation will be encapsulated in
  71
  72 HTTP Response 422 Unprocessable entity
  73
  74
  75 ===== Parameters
  76
  77 [options="header", cols=".^2,.^3,.^9,.^4"]
  78 |===
  79 |Type|Name|Description|Schema
  80 |**Query**|**category** +
  81 __optional__|Service Category (filter)|string
  82 |**Query**|**distributionStatus** +
  83 __optional__|Service distribution status (filter)|string
  84 |**Query**|**fields** +
  85 __optional__|Field selection - used to filtering the attributes to be retreived|string
  86 |===
  87
  88
  89 ===== Responses
  90
  91 [options="header", cols=".^2,.^14,.^4"]
  92 |===
  93 |HTTP Code|Description|Schema
  94 |**200**|Success|< <<_servicespecification,ServiceSpecification>> > array
  95 |**400**|Bad Request
  96
  97 List of supported error codes:
  98 - 20: Invalid URL parameter value
  99 - 21: Missing body
 100 - 22: Invalid body
 101 - 23: Missing body field
 102 - 24: Invalid body field
 103 - 25: Missing header
 104 - 26: Invalid header value
 105 - 27: Missing query-string parameter
 106 - 28: Invalid query-string parameter value|<<_errorrepresentation,ErrorRepresentation>>
 107 |**401**|Unauthorized
 108
 109 List of supported error codes:
 110 - 40: Missing credentials
 111 - 41: Invalid credentials
 112 - 42: Expired credentials|<<_errorrepresentation,ErrorRepresentation>>
 113 |**403**|Forbidden
 114
 115 List of supported error codes:
 116 - 50: Access denied
 117 - 51: Forbidden requester
 118 - 52: Forbidden user
 119 - 53: Too many requests|<<_errorrepresentation,ErrorRepresentation>>
 120 |**404**|Not Found
 121
 122 List of supported error codes:
 123 - 60: Resource not found|<<_errorrepresentation,ErrorRepresentation>>
 124 |**422**|Unprocessable entity
 125
 126 Functional error|<<_errorrepresentation,ErrorRepresentation>>
 127 |**500**|Internal Server Error
 128
 129 List of supported error codes:
 130 - 1: Internal error|<<_errorrepresentation,ErrorRepresentation>>
 131 |**503**|Service Unavailable
 132
 133 List of supported error codes:
 134 - 5: The service is temporarily unavailable
 135 - 6: Orange API is over capacity, retry later !|<<_errorrepresentation,ErrorRepresentation>>
 136 |===
 137
 138
 139 [[_servicespecificationget]]
 140 ==== Retrieve a service specification
 141 ....
 142 GET /serviceSpecification/{id}
 143 ....
 144
 145
 146 ===== Description
 147 This operation returns a service specification by its id from a catalog. Attribute selection is enabled using the fields attribute.
 148
 149 Specific business errors for current operation will be encapsulated in
 150
 151 HTTP Response 422 Unprocessable entity
 152
 153
 154 ===== Parameters
 155
 156 [options="header", cols=".^2,.^3,.^9,.^4"]
 157 |===
 158 |Type|Name|Description|Schema
 159 |**Path**|**id** +
 160 __required__||string
 161 |**Query**|**fields** +
 162 __optional__|Attribute selection|string
 163 |===
 164
 165
 166 ===== Responses
 167
 168 [options="header", cols=".^2,.^14,.^4"]
 169 |===
 170 |HTTP Code|Description|Schema
 171 |**200**|Success|<<_servicespecification,ServiceSpecification>>
 172 |**400**|Bad Request
 173
 174 List of supported error codes:
 175 - 20: Invalid URL parameter value
 176 - 21: Missing body
 177 - 22: Invalid body
 178 - 23: Missing body field
 179 - 24: Invalid body field
 180 - 25: Missing header
 181 - 26: Invalid header value
 182 - 27: Missing query-string parameter
 183 - 28: Invalid query-string parameter value|<<_errorrepresentation,ErrorRepresentation>>
 184 |**401**|Unauthorized
 185
 186 List of supported error codes:
 187 - 40: Missing credentials
 188 - 41: Invalid credentials
 189 - 42: Expired credentials|<<_errorrepresentation,ErrorRepresentation>>
 190 |**403**|Forbidden
 191
 192 List of supported error codes:
 193 - 50: Access denied
 194 - 51: Forbidden requester
 195 - 52: Forbidden user
 196 - 53: Too many requests|<<_errorrepresentation,ErrorRepresentation>>
 197 |**404**|Not Found
 198
 199 List of supported error codes:
 200 - 60: Resource not found|<<_errorrepresentation,ErrorRepresentation>>
 201 |**422**|Unprocessable entity
 202
 203 Functional error|<<_errorrepresentation,ErrorRepresentation>>
 204 |**500**|Internal Server Error
 205
 206 List of supported error codes:
 207 - 1: Internal error|<<_errorrepresentation,ErrorRepresentation>>
 208 |**503**|Service Unavailable
 209
 210 List of supported error codes:
 211 - 5: The service is temporarily unavailable
 212 - 6: Orange API is over capacity, retry later !|<<_errorrepresentation,ErrorRepresentation>>
 213 |===
 214
 215
 216 [[_definitions]]
 217 == Definitions
 218
 219 [[_attachment]]
 220 === Attachment
 221 An attachment is a file uses to describe the service.
 222 In nbi we use attachment to retrieve ONAP artifacts.
 223
 224
 225 [options="header", cols=".^3,.^11,.^4"]
 226 |===
 227 |Name|Description|Schema
 228 |**@type** +
 229 __optional__|This attribute allows to dynamically extends TMF class. Valued with 'ONAPartifact'. We used this features to add following attributes:
 230 artifactLabel
 231 artifactGroupType
 232 artifactTimeout
 233 artifactChecksum
 234 artifactVersion
 235 generatedFromUUID +
 236 **Default** : `"ONAPartifact"`|string
 237 |**artifactChecksum** +
 238 __optional__|Additional attribute (not in the TMF API) - extended through @type - artifactChecksum|string
 239 |**artifactGroupType** +
 240 __optional__|Additional attribute (not in the TMF API) - extended through @type - artifactGroupType|string
 241 |**artifactLabel** +
 242 __optional__|Additional attribute (not in the TMF API) - extended through @type - artifactLabel|string
 243 |**artifactTimeout** +
 244 __optional__|Additional attribute (not in the TMF API) - extended through @type - artifactTimeout|string
 245 |**artifactVersion** +
 246 __optional__|Additional attribute (not in the TMF API) - extended through @type - artifactVersion|string
 247 |**description** +
 248 __optional__|Description of the attachment - filled with artifactDescription|string
 249 |**generatedFromUUID** +
 250 __optional__|Additional attribute (not in the TMF API) - extended through @type - generatedFromUUID|string
 251 |**id** +
 252 __optional__|Unique identifier of the attachment - filled with artifactUUID.|string
 253 |**mimeType** +
 254 __optional__|Filled with artifactType|string
 255 |**name** +
 256 __optional__|Name of the attachment - filled with artifactName|string
 257 |**url** +
 258 __optional__|Uniform Resource Locator, is a web page address - filled with artifactURL|string
 259 |===
 260
 261
 262 [[_distributionstatus]]
 263 === DistributionStatus
 264 Service distribution status from ONAP.
 265
 266 __Type__ : enum (DISTRIBUTION_NOT_APPROVED, DISTRIBUTION_APPROVED, DISTRIBUTED, DISTRIBUTION_REJECTED)
 267
 268
 269 [[_errorrepresentation]]
 270 === ErrorRepresentation
 271 This class is used to describe error.
 272 for nbi Beijing release we do not manage additional error for serviceCatalog
 273
 274
 275 [options="header", cols=".^3,.^11,.^4"]
 276 |===
 277 |Name|Description|Schema
 278 |**@schemaLocation** +
 279 __optional__|it provides a link to the schema describing a REST resource.|string
 280 |**@type** +
 281 __optional__|The class type of a REST resource.|string
 282 |**code** +
 283 __required__|Application related code (as defined in the API or from a common list)|integer (int32)
 284 |**message** +
 285 __optional__|Text that provide more details and corrective actions related to the error. This can be shown to a client user|string
 286 |**reason** +
 287 __required__|Text that explains the reason for error. This can be shown to a client user.|string
 288 |**referenceErrror** +
 289 __optional__|url pointing to documentation describing the error|string
 290 |**status** +
 291 __optional__|http error code extension like 400-2|string
 292 |===
 293
 294
 295 [[_lifecyclestatusvalues]]
 296 === LifecycleStatusValues
 297 Service lifecycle value from ONAP SDC
 298
 299 __Type__ : enum (NOT_CERTIFIED_CHECKOUT, NOT_CERTIFIED_CHECKIN, READY_FOR_CERTIFICATION, CERTIFICATION_IN_PROGRESS, CERTIFIED)
 300
 301
 302 [[_relatedpartyref]]
 303 === RelatedPartyRef
 304 Party linked to the service catalog.
 305 in nbi we retrieve information about last updater of the service in SDC
 306
 307
 308 [options="header", cols=".^3,.^11,.^4"]
 309 |===
 310 |Name|Description|Schema
 311 |**id** +
 312 __optional__|Unique identifier of the related party. Filled with lastUpdaterUserId|string
 313 |**name** +
 314 __optional__|Name of the related party - Filled with lastUpdatedFullName|string
 315 |**role** +
 316 __optional__|Role payed by the related party
 317 Only role 'lastUpdater' is retrieved in Beijing release|string
 318 |===
 319
 320
 321 [[_resourcespecificationref]]
 322 === ResourceSpecificationRef
 323 A list of resourceSpec identified to deliver the service.
 324 for nbi we retrieve resource information available in service description (through SDC api) bu as well information retrieved in the TOSCA file.
 325
 326
 327 [options="header", cols=".^3,.^11,.^4"]
 328 |===
 329 |Name|Description|Schema
 330 |**@type** +
 331 __optional__|This attribute allows to dynamically extends TMF class. Valued with: 'ONAPresource'. We used this features to add following attributes:
 332 resourceInstanceName
 333 resourceInvariantUUID
 334 resourceType
 335 modelCustomizationName
 336 modelCustomizationId +
 337 **Default** : `"ONAPresource"`|string
 338 |**id** +
 339 __optional__|Unique identifier of the resource specification - filled with resourceUUID|string
 340 |**modelCustomizationId** +
 341 __optional__|Additional attribute (not in the TMF API) - extended through @type - Retrieved in the TOSCA file : attribute customizationUUID in topology_template/node_template for the resource|string
 342 |**modelCustomizationName** +
 343 __optional__|Additional attribute (not in the TMF API) - extended through @type - Retrieved in the TOSCA file : attribute name in topology_template/node_template for the resource|string
 344 |**name** +
 345 __optional__|Name of the resource specification - filled with resourceName|string
 346 |**resourceInstanceName** +
 347 __optional__|Additional attribute (not in the TMF API) - extended through @type - resourceInstanceName|string
 348 |**resourceInvariantUUID** +
 349 __optional__|Additional attribute (not in the TMF API) - extended through @type - resourceInvariantUUID|string
 350 |**resourceType** +
 351 __optional__|Additional attribute (not in the TMF API) - extended through @type - resoucreType|string
 352 |**version** +
 353 __optional__|Version for this resource specification - filled with resourceVersion|string
 354 |===
 355
 356
 357 [[_servicespeccharacteristic]]
 358 === ServiceSpecCharacteristic
 359 A characteristic quality or distinctive feature of a ServiceSpecification.
 360 ServiceSpecCharacteristic are retrieved in the serviceTosca file in the topology_template section in the inputs section.
 361
 362
 363 [options="header", cols=".^3,.^11,.^4"]
 364 |===
 365 |Name|Description|Schema
 366 |**@schemaLocation** +
 367 __optional__|An url pointing to type description - we do not use it in nbi Beijing release|string
 368 |**@type** +
 369 __optional__|This attribute allows to dynamically extends TMF class. Valued with: 'ONAPserviceCharacteristic'. We do not used this features in nbi Beijing release.|string
 370 |**description** +
 371 __optional__|A narrative that explains in detail what the characteristic is - Filled with parameter_description|string
 372 |**name** +
 373 __optional__|Name of the characteristic - Filled with parameter_name|string
 374 |**required** +
 375 __optional__|A parameter to define if the characteristic is mandatory - Filled from parameter_required – if not fielded by default ‘true’ +
 376 **Default** : `true`|boolean
 377 |**serviceSpecCharacteristicValue** +
 378 __optional__||< <<_servicespeccharacteristicvalue,ServiceSpecCharacteristicValue>> > array
 379 |**status** +
 380 __optional__|Status of the characteristic - filled with status_value|string
 381 |**valueType** +
 382 __optional__|A kind of value that the characteristic can take on, such as numeric, text and so forth - Filled with parameter_type|string
 383 |===
 384
 385
 386 [[_servicespeccharacteristicvalue]]
 387 === ServiceSpecCharacteristicValue
 388 A number or text that can be assigned to a service specification characteristic.
 389 ServiceSpecCharacteristicValue are retrieved in the service Tosca file
 390
 391
 392 [options="header", cols=".^3,.^11,.^4"]
 393 |===
 394 |Name|Description|Schema
 395 |**isDefault** +
 396 __optional__|Information calculated from parameter default in the Tosca file|boolean
 397 |**value** +
 398 __optional__|A discrete value that the characteristic can take on|string
 399 |**valueType** +
 400 __optional__|A kind of value that the characteristic can take on, such as numeric, text, and so forth
 401 Retrieved in the Tosca in the topology_template section in the inputs section - parameter_type.
 402 We do not manage parameter_type= list or map for Beijing release|string
 403 |===
 404
 405
 406 [[_servicespecification]]
 407 === ServiceSpecification
 408 ServiceSpecification is a class that offers characteristics to describe a type of service. Functionally, it acts as a template by which Services may be instantiated. By sharing the same specification, these services would therefore share the same set of characteristics.
 409 the service information are retrieved in SDC
 410
 411
 412 [options="header", cols=".^3,.^11,.^4"]
 413 |===
 414 |Name|Description|Schema
 415 |**@baseType** +
 416 __optional__|Not used for Beijing release|string
 417 |**@schemaLocation** +
 418 __optional__|Not used for Beijing release|string
 419 |**@type** +
 420 __optional__|This attribute allows to dynamically extends TMF class. Valued with 'ONAPservice'. We used this features to add following attributes:
 421 invariantUUID
 422 toscaModelURL
 423 toscaResourceName
 424 category (1)
 425 subcategory (1)
 426 distributionStatus +
 427 **Default** : `"ONAPservice"`|string
 428 |**attachment** +
 429 __optional__||< <<_attachment,Attachment>> > array
 430 |**category** +
 431 __optional__|Additional attribute - extended through @type - category
 432 Please note that this attribute is managed in TMF - in future release we'll introduce category resource|string
 433 |**description** +
 434 __optional__|A narrative that explains in detail what the service specification is - Filled with SDC Service description|string
 435 |**distributionStatus** +
 436 __optional__||<<_distributionstatus,DistributionStatus>>
 437 |**href** +
 438 __optional__|Reference of the service specification- not mapped in Beijing|string
 439 |**id** +
 440 __optional__|Unique identifier of the service specification. Filled with SDC Service uuid|string
 441 |**invariantUUID** +
 442 __required__|Additional attribute (not in the TMF API) - extended through @type - invariantUUID|string
 443 |**lifecycleStatus** +
 444 __optional__||<<_lifecyclestatusvalues,LifecycleStatusValues>>
 445 |**name** +
 446 __optional__|Name of the service specification- Filled with SDC Service name|string
 447 |**relatedParty** +
 448 __optional__||< <<_relatedpartyref,RelatedPartyRef>> > array
 449 |**resourceSpecification** +
 450 __optional__||< <<_resourcespecificationref,ResourceSpecificationRef>> > array
 451 |**serviceSpecCharacteristic** +
 452 __optional__||< <<_servicespeccharacteristic,ServiceSpecCharacteristic>> > array
 453 |**subcategory** +
 454 __optional__|Additional attribute - extended through @type - category
 455 Please note that this attribute is managed in TMF - in future release we'll introduce category resourc|string
 456 |**targetServiceSchema** +
 457 __optional__||<<_targetserviceschemaref,TargetServiceSchemaRef>>
 458 |**toscaModelURL** +
 459 __optional__|Additional attribute (not in the TMF API) - extended through @type - toscaModelURL|string
 460 |**toscaResourceName** +
 461 __optional__|Additional attribute (not in the TMF API) - extended through @type - toscaResourceName|string
 462 |**version** +
 463 __optional__|Service specification version - Filled with SDC Service version|string
 464 |===
 465
 466
 467 [[_targetserviceschemaref]]
 468 === TargetServiceSchemaRef
 469
 470 [options="header", cols=".^3,.^4"]
 471 |===
 472 |Name|Schema
 473 |**@schemaLocation** +
 474 __required__|string
 475 |**@type** +
 476 __required__|string
 477 |===
 478
 479
 480 [[_timeperiod]]
 481 === TimePeriod
 482 A time period
 483
 484
 485 [options="header", cols=".^3,.^11,.^4"]
 486 |===
 487 |Name|Description|Schema
 488 |**endDateTime** +
 489 __optional__|End date and time of the period|string (date-time)
 490 |**startDateTime** +
 491 __optional__|Start date and time of the period|string (date-time)
 492 |===
 493