docs/offeredapis/serviceCatalog/asciiDoc.adoc

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