docs/offeredapis/serviceCatalog/markDown.md

   1 # API ServiceCatalog
   2
   3
   4 <a name="overview"></a>
   5 ## Overview
   6
   7 ### Api URL
   8
   9 [Swagger UI](https://api-designer.sso.infra.ftgroup/swagger-ui/?url=https://api-designer.sso.infra.ftgroup/api/1.0/apis/XOmvoxNn9d/swagger.json)
  10
  11
  12 [plant UML UI](https://plantuml.rd.francetelecom.fr/proxy?fmt=svg&src=https://api-designer.sso.infra.ftgroup/api/1.0/apis/XOmvoxNn9d/plantuml&noCache=995303.0)
  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 & byList) for resource serviceSpecification is available
  17
  18
  19 ### Version information
  20 *Version* : 3.0.0_inProgress
  21
  22
  23 ### URI scheme
  24 *Host* : serverRoot
  25 *BasePath* : /nbi/api/v3
  26 *Schemes* : HTTPS
  27
  28
  29 ### Tags
  30
  31 * ServiceSpecification
  32
  33
  34 ### Produces
  35
  36 * `application/json;charset=utf-8`
  37
  38
  39 <a name="paths"></a>
  40 ## Resources
  41
  42 <a name="servicespecification_resource"></a>
  43 ### ServiceSpecification
  44
  45 <a name="servicespecificationfind"></a>
  46 #### List service specifications
  47 ```
  48 GET /serviceSpecification
  49 ```
  50
  51
  52 ##### Description
  53 This operation returns service specifications from a catalog.
  54 Only a predefined set of attribute is proposed : Based on SDC limitations, only attributes category and distributionStatus are available for serviceSpecification filtering
  55 Fields attribute could be used to filter attributes retrieved
  56
  57 Specific business errors for current operation will be encapsulated in
  58
  59 HTTP Response 422 Unprocessable entity
  60
  61
  62 ##### Parameters
  63
  64 |Type|Name|Description|Schema|
  65 |---|---|---|---|
  66 |**Query**|**category**  <br>*optional*|Service Category (filter)|string|
  67 |**Query**|**distributionStatus**  <br>*optional*|Service distribution status (filter)|string|
  68 |**Query**|**fields**  <br>*optional*|Field selection - used to filtering the attributes to be retreived|string|
  69
  70
  71 ##### Responses
  72
  73 |HTTP Code|Description|Schema|
  74 |---|---|---|
  75 |**200**|Success|< [ServiceSpecification](#servicespecification) > array|
  76 |**400**|Bad Request<br><br>List of supported error codes:<br>- 20: Invalid URL parameter value<br>- 21: Missing body<br>- 22: Invalid body<br>- 23: Missing body field<br>- 24: Invalid body field<br>- 25: Missing header<br>- 26: Invalid header value<br>- 27: Missing query-string parameter<br>- 28: Invalid query-string parameter value|[ErrorRepresentation](#errorrepresentation)|
  77 |**401**|Unauthorized<br><br>List of supported error codes:<br>- 40: Missing credentials<br>- 41: Invalid credentials<br>- 42: Expired credentials|[ErrorRepresentation](#errorrepresentation)|
  78 |**403**|Forbidden<br><br>List of supported error codes:<br>- 50: Access denied<br>- 51: Forbidden requester<br>- 52: Forbidden user<br>- 53: Too many requests|[ErrorRepresentation](#errorrepresentation)|
  79 |**404**|Not Found<br><br>List of supported error codes:<br>- 60: Resource not found|[ErrorRepresentation](#errorrepresentation)|
  80 |**422**|Unprocessable entity<br><br>Functional error|[ErrorRepresentation](#errorrepresentation)|
  81 |**500**|Internal Server Error<br><br>List of supported error codes:<br>- 1: Internal error|[ErrorRepresentation](#errorrepresentation)|
  82 |**503**|Service Unavailable<br><br>List of supported error codes:<br>- 5: The service is temporarily unavailable<br>- 6: Orange API is over capacity, retry later !|[ErrorRepresentation](#errorrepresentation)|
  83
  84
  85 ##### Produces
  86
  87 * `application/json;charset=utf-8`
  88
  89
  90 <a name="servicespecificationget"></a>
  91 #### Retrieve a service specification
  92 ```
  93 GET /serviceSpecification/{id}
  94 ```
  95
  96
  97 ##### Description
  98 This operation returns a service specification by its id from a catalog. Attribute selection is enabled using the fields attribute.
  99
 100 Specific business errors for current operation will be encapsulated in
 101
 102 HTTP Response 422 Unprocessable entity
 103
 104
 105 ##### Parameters
 106
 107 |Type|Name|Description|Schema|
 108 |---|---|---|---|
 109 |**Path**|**id**  <br>*required*||string|
 110 |**Query**|**fields**  <br>*optional*|Attribute selection|string|
 111
 112
 113 ##### Responses
 114
 115 |HTTP Code|Description|Schema|
 116 |---|---|---|
 117 |**200**|Success|[ServiceSpecification](#servicespecification)|
 118 |**400**|Bad Request<br><br>List of supported error codes:<br>- 20: Invalid URL parameter value<br>- 21: Missing body<br>- 22: Invalid body<br>- 23: Missing body field<br>- 24: Invalid body field<br>- 25: Missing header<br>- 26: Invalid header value<br>- 27: Missing query-string parameter<br>- 28: Invalid query-string parameter value|[ErrorRepresentation](#errorrepresentation)|
 119 |**401**|Unauthorized<br><br>List of supported error codes:<br>- 40: Missing credentials<br>- 41: Invalid credentials<br>- 42: Expired credentials|[ErrorRepresentation](#errorrepresentation)|
 120 |**403**|Forbidden<br><br>List of supported error codes:<br>- 50: Access denied<br>- 51: Forbidden requester<br>- 52: Forbidden user<br>- 53: Too many requests|[ErrorRepresentation](#errorrepresentation)|
 121 |**404**|Not Found<br><br>List of supported error codes:<br>- 60: Resource not found|[ErrorRepresentation](#errorrepresentation)|
 122 |**422**|Unprocessable entity<br><br>Functional error|[ErrorRepresentation](#errorrepresentation)|
 123 |**500**|Internal Server Error<br><br>List of supported error codes:<br>- 1: Internal error|[ErrorRepresentation](#errorrepresentation)|
 124 |**503**|Service Unavailable<br><br>List of supported error codes:<br>- 5: The service is temporarily unavailable<br>- 6: Orange API is over capacity, retry later !|[ErrorRepresentation](#errorrepresentation)|
 125
 126
 127 ##### Produces
 128
 129 * `application/json;charset=utf-8`
 130
 131
 132 <a name="definitions"></a>
 133 ## Definitions
 134
 135 <a name="attachment"></a>
 136 ### Attachment
 137 An attachment is a file uses to describe the service.
 138 In nbi we use attachment to retrieve ONAP artifacts.
 139
 140
 141 |Name|Description|Schema|
 142 |---|---|---|
 143 |**@type**  <br>*optional*|This attribute allows to dynamically extends TMF class. Valued with 'ONAPartifact'. We used this features to add following attributes: <br>artifactLabel<br>artifactGroupType<br>artifactTimeout<br>artifactChecksum<br>artifactVersion<br>generatedFromUUID  <br>**Default** : `"ONAPartifact"`|string|
 144 |**artifactChecksum**  <br>*optional*|Additional attribute (not in the TMF API) - extended through @type - artifactChecksum|string|
 145 |**artifactGroupType**  <br>*optional*|Additional attribute (not in the TMF API) - extended through @type - artifactGroupType|string|
 146 |**artifactLabel**  <br>*optional*|Additional attribute (not in the TMF API) - extended through @type - artifactLabel|string|
 147 |**artifactTimeout**  <br>*optional*|Additional attribute (not in the TMF API) - extended through @type - artifactTimeout|string|
 148 |**artifactVersion**  <br>*optional*|Additional attribute (not in the TMF API) - extended through @type - artifactVersion|string|
 149 |**description**  <br>*optional*|Description of the attachment - filled with artifactDescription|string|
 150 |**generatedFromUUID**  <br>*optional*|Additional attribute (not in the TMF API) - extended through @type - generatedFromUUID|string|
 151 |**id**  <br>*optional*|Unique identifier of the attachment - filled with artifactUUID.|string|
 152 |**mimeType**  <br>*optional*|Filled with artifactType|string|
 153 |**name**  <br>*optional*|Name of the attachment - filled with artifactName|string|
 154 |**url**  <br>*optional*|Uniform Resource Locator, is a web page address - filled with artifactURL|string|
 155
 156
 157 <a name="distributionstatus"></a>
 158 ### DistributionStatus
 159 Service distribution status from ONAP.
 160
 161 *Type* : enum (DISTRIBUTION_NOT_APPROVED, DISTRIBUTION_APPROVED, DISTRIBUTED, DISTRIBUTION_REJECTED)
 162
 163
 164 <a name="errorrepresentation"></a>
 165 ### ErrorRepresentation
 166 This class is used to describe error.
 167 for nbi Beijing release we do not manage additional error for serviceCatalog
 168
 169
 170 |Name|Description|Schema|
 171 |---|---|---|
 172 |**@schemaLocation**  <br>*optional*|it provides a link to the schema describing a REST resource.|string|
 173 |**@type**  <br>*optional*|The class type of a REST resource.|string|
 174 |**code**  <br>*required*|Application related code (as defined in the API or from a common list)|integer (int32)|
 175 |**message**  <br>*optional*|Text that provide more details and corrective actions related to the error. This can be shown to a client user|string|
 176 |**reason**  <br>*required*|Text that explains the reason for error. This can be shown to a client user.|string|
 177 |**referenceErrror**  <br>*optional*|url pointing to documentation describing the error|string|
 178 |**status**  <br>*optional*|http error code extension like 400-2|string|
 179
 180
 181 <a name="lifecyclestatusvalues"></a>
 182 ### LifecycleStatusValues
 183 Service lifecycle value from ONAP SDC
 184
 185 *Type* : enum (NOT_CERTIFIED_CHECKOUT, NOT_CERTIFIED_CHECKIN, READY_FOR_CERTIFICATION, CERTIFICATION_IN_PROGRESS, CERTIFIED)
 186
 187
 188 <a name="relatedpartyref"></a>
 189 ### RelatedPartyRef
 190 Party linked to the service catalog.
 191 in nbi we retrieve information about last updater of the service in SDC
 192
 193
 194 |Name|Description|Schema|
 195 |---|---|---|
 196 |**id**  <br>*optional*|Unique identifier of the related party. Filled with lastUpdaterUserId|string|
 197 |**name**  <br>*optional*|Name of the related party - Filled with lastUpdatedFullName|string|
 198 |**role**  <br>*optional*|Role payed by the related party<br>Only role 'lastUpdater' is retrieved in Beijing release|string|
 199
 200
 201 <a name="resourcespecificationref"></a>
 202 ### ResourceSpecificationRef
 203 A list of resourceSpec identified to deliver the service.
 204 for nbi we retrieve resource information available in service description (through SDC api) bu as well information retrieved in the TOSCA file.
 205
 206
 207 |Name|Description|Schema|
 208 |---|---|---|
 209 |**@type**  <br>*optional*|This attribute allows to dynamically extends TMF class. Valued with: 'ONAPresource'. We used this features to add following attributes:<br>resourceInstanceName<br>resourceInvariantUUID<br>resourceType<br>modelCustomizationName<br>modelCustomizationId  <br>**Default** : `"ONAPresource"`|string|
 210 |**id**  <br>*optional*|Unique identifier of the resource specification - filled with resourceUUID|string|
 211 |**modelCustomizationId**  <br>*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|
 212 |**modelCustomizationName**  <br>*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|
 213 |**name**  <br>*optional*|Name of the resource specification - filled with resourceName|string|
 214 |**resourceInstanceName**  <br>*optional*|Additional attribute (not in the TMF API) - extended through @type - resourceInstanceName|string|
 215 |**resourceInvariantUUID**  <br>*optional*|Additional attribute (not in the TMF API) - extended through @type - resourceInvariantUUID|string|
 216 |**resourceType**  <br>*optional*|Additional attribute (not in the TMF API) - extended through @type - resoucreType|string|
 217 |**version**  <br>*optional*|Version for this resource specification - filled with resourceVersion|string|
 218
 219
 220 <a name="servicespeccharacteristic"></a>
 221 ### ServiceSpecCharacteristic
 222 A characteristic quality or distinctive feature of a ServiceSpecification.
 223 ServiceSpecCharacteristic are retrieved in the serviceTosca file in the topology_template section in the inputs section.
 224
 225
 226 |Name|Description|Schema|
 227 |---|---|---|
 228 |**@schemaLocation**  <br>*optional*|An url pointing to type description - we do not use it in nbi Beijing release|string|
 229 |**@type**  <br>*optional*|This attribute allows to dynamically extends TMF class. Valued with: 'ONAPserviceCharacteristic'. We do not used this features in nbi Beijing release.|string|
 230 |**description**  <br>*optional*|A narrative that explains in detail what the characteristic is - Filled with parameter_description|string|
 231 |**name**  <br>*optional*|Name of the characteristic - Filled with parameter_name|string|
 232 |**required**  <br>*optional*|A parameter to define if the characteristic is mandatory - Filled from parameter_required – if not fielded by default ‘true’  <br>**Default** : `true`|boolean|
 233 |**serviceSpecCharacteristicValue**  <br>*optional*||< [ServiceSpecCharacteristicValue](#servicespeccharacteristicvalue) > array|
 234 |**status**  <br>*optional*|Status of the characteristic - filled with status_value|string|
 235 |**valueType**  <br>*optional*|A kind of value that the characteristic can take on, such as numeric, text and so forth - Filled with parameter_type|string|
 236
 237
 238 <a name="servicespeccharacteristicvalue"></a>
 239 ### ServiceSpecCharacteristicValue
 240 A number or text that can be assigned to a service specification characteristic.
 241 ServiceSpecCharacteristicValue are retrieved in the service Tosca file
 242
 243
 244 |Name|Description|Schema|
 245 |---|---|---|
 246 |**isDefault**  <br>*optional*|Information calculated from parameter default in the Tosca file|boolean|
 247 |**value**  <br>*optional*|A discrete value that the characteristic can take on|string|
 248 |**valueType**  <br>*optional*|A kind of value that the characteristic can take on, such as numeric, text, and so forth<br>Retrieved in the Tosca in the topology_template section in the inputs section - parameter_type. <br>We do not manage parameter_type= list or map for Beijing release|string|
 249
 250
 251 <a name="servicespecification"></a>
 252 ### ServiceSpecification
 253 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.
 254 the service information are retrieved in SDC
 255
 256
 257 |Name|Description|Schema|
 258 |---|---|---|
 259 |**@baseType**  <br>*optional*|Not used for Beijing release|string|
 260 |**@schemaLocation**  <br>*optional*|Not used for Beijing release|string|
 261 |**@type**  <br>*optional*|This attribute allows to dynamically extends TMF class. Valued with 'ONAPservice'. We used this features to add following attributes:<br>invariantUUID<br>toscaModelURL<br>toscaResourceName<br>category (1)<br>subcategory (1)<br>distributionStatus  <br>**Default** : `"ONAPservice"`|string|
 262 |**attachment**  <br>*optional*||< [Attachment](#attachment) > array|
 263 |**category**  <br>*optional*|Additional attribute - extended through @type - category<br>Please note that this attribute is managed in TMF - in future release we'll introduce category resource|string|
 264 |**description**  <br>*optional*|A narrative that explains in detail what the service specification is - Filled with SDC Service description|string|
 265 |**distributionStatus**  <br>*optional*||[DistributionStatus](#distributionstatus)|
 266 |**href**  <br>*optional*|Reference of the service specification- not mapped in Beijing|string|
 267 |**id**  <br>*optional*|Unique identifier of the service specification. Filled with SDC Service uuid|string|
 268 |**invariantUUID**  <br>*required*|Additional attribute (not in the TMF API) - extended through @type - invariantUUID|string|
 269 |**lifecycleStatus**  <br>*optional*||[LifecycleStatusValues](#lifecyclestatusvalues)|
 270 |**name**  <br>*optional*|Name of the service specification- Filled with SDC Service name|string|
 271 |**relatedParty**  <br>*optional*||< [RelatedPartyRef](#relatedpartyref) > array|
 272 |**resourceSpecification**  <br>*optional*||< [ResourceSpecificationRef](#resourcespecificationref) > array|
 273 |**serviceSpecCharacteristic**  <br>*optional*||< [ServiceSpecCharacteristic](#servicespeccharacteristic) > array|
 274 |**subcategory**  <br>*optional*|Additional attribute - extended through @type - category<br>Please note that this attribute is managed in TMF - in future release we'll introduce category resourc|string|
 275 |**targetServiceSchema**  <br>*optional*||[TargetServiceSchemaRef](#targetserviceschemaref)|
 276 |**toscaModelURL**  <br>*optional*|Additional attribute (not in the TMF API) - extended through @type - toscaModelURL|string|
 277 |**toscaResourceName**  <br>*optional*|Additional attribute (not in the TMF API) - extended through @type - toscaResourceName|string|
 278 |**version**  <br>*optional*|Service specification version - Filled with SDC Service version|string|
 279
 280
 281 <a name="targetserviceschemaref"></a>
 282 ### TargetServiceSchemaRef
 283
 284 |Name|Schema|
 285 |---|---|
 286 |**@schemaLocation**  <br>*required*|string|
 287 |**@type**  <br>*required*|string|
 288
 289
 290 <a name="timeperiod"></a>
 291 ### TimePeriod
 292 A time period
 293
 294
 295 |Name|Description|Schema|
 296 |---|---|---|
 297 |**endDateTime**  <br>*optional*|End date and time of the period|string (date-time)|
 298 |**startDateTime**  <br>*optional*|Start date and time of the period|string (date-time)|
 299