docs/offeredapis/api_serviceInventory/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: "# About the ONAP Service Inventory API\n The Service Inventory API is based on a subset of the TM Forum 638 Service Inventory API.\n## API Overview\n### General Description \nThis Service Inventory API is used to retrieve the Service Instances from the ONAP inventory. As Services are ordered from ONAP via the Service Order API, the Service Inventory API allows external systems such as the Business Support Systems (BSS) to discover the Services that have been created in the ONAP Inventory.\n\nThe Service Design Center (SDC) of ONAP allows for the creation of Services that can be orchestrated by ONAP. Once a Service from the Catalog is ordered, the ONAP Service Orchestrator will create a Service Instance within the AAI of ONAP. This API allows a representation of the Service Inventory in TMF 638 format. The Service Inventory API also supports inventory notifications to external listeners. A List of available subscription for serviceInventory notifications, see /hub resources for more information:\n\n- ServiceCreationNotification\n- ServiceAttributeValueChangeNotification\n- ServiceRemoveNotification\n\n \n### Relationship and Dependencies\n This Service Inventory API is related to the TM Forum 638 Service Inventory API and also to MEF LSO LEGATO Service Inventory API.\n\nThis API takes a subset of the Service Inventory API, namely the Service resource, and maps this standard resource to the ONAP AAI Service Instance. By doing this we allow a well known, standardized JSON REST representation of the Service Instances available in ONAP to be visible by external systems. \n\n### API Structure and Approach\nThe Service Inventory API can be used to get the details of a specific ONAP Service Instance, or can be used to search/list the Service Instances that are in the ONAP AAI. \n## Getting Started with the API (Hello World)\nThe Service Inventory API is available via two schemes, http and https. For interacting with the API the simplest method is via http. To interact with the this API via https, your Client would be required to load the neccessary https certificate. \n\nThe default installation of ONAP via OOM, will configure the use of two Node ports for External APIs. NodePorts are used to allow client applications, that run outside of Kubernetes, access to ONAP components deployed by OOM. For this Service Inventory API, the External API Framework has a http Node port of 30274. For https, the Node port is 30292.\n\n From outside ONAP, a client can interact with External API by first getting the IP that the NBI docker container is running on, and then using the appropriate nodeport according to the access scheme. For example to access this Service Inventory API to retrieve a list of all Service Instances available in ONAP you can use http method GET to http://{nbi_ip}:30274/nbi/api/v4/service/ \n### SDK quick intro\nThere are many tools that can be used to view and edit this swagger file like swagger editor, Atom and senya. For example this swagger file can be loaded into https://editor.swagger.io/. This UI acts both as an online editor and viewer. \n### How to start the client side implementation\n* Code generation, is available via the Generate Client option in the swagger editor. Client stubs can be generated in multiple languages, for example java, go, python etc. These Client stub code can be incorporated in the Application you wish to access the Service Inventory API from.\n\n### How to start the server side implementation\n* Not applicable, the service side for this API will be the NBI container running the External API Framework Springboot application.\n\n## API Description\nIncludes summary of information drawn from API definitions in OpenAPI / Swagger files\n### Resource Endpoint / Resource Quick Reference\nGET /service/ : This operation returns a list service instances from AAI\n\nGET /service/{id} : This operation returns the specific service instance associated with this id. Note the id maps to the service-instance-id of the service-instance object in AAI.\n\n### Data Schema\n#### Main API Entities\nDescribe the major entities used in the API\n\nThe main entity of the API is the Service resource. This entity is the top level entity of the API, and is returned as either a single instance when queried with id, or as JSON arroy of Service entities when queried as a list.\n\nThe major child enties are relatedParty which points to the Customer who ordered the Service. The serviceSpecification which points to the Service template in SDC Catalog that was used to create this service instance.\n#### Payload data structures\nIf any, describe the appropriate data structures that are included within payload of the API.\n\nNot applicable\n### Security on the API\nAuthentication; Authorization; Credentials/access token; etc.\n\n https certificate required if using https. No authentication on http requests.In production this API should be behind an API Gateway with the necessary authentication\n### Response Codes\nThe meaning of Status Codes & Errors\n\nSee response codes for each API resource in the API section below\n### Rate Limits and Thresholds\nRequests per unit time allowed; Pagination\n\n No rate limits or thresholds, in production this API should be behind an API Gateway with the necessary limits.\n### Validation constraints\nDescribe any behavioral and structural validation constraints\n\nNot applicable\n### Assumptions\nFor example, any Pre/Post conditions\n\n For this API to function and return Service Instances, SDC is required to be running and Service models designed in the SDC catalog that have been ordered and instantiated by SO in AAI.\n## API Interactions and Flows\n### Interaction Examples\nIllustrate sequence of client calls to this API, possibly based on Use Cases, presented with diagrams, tables, etc\n\nThe Service Inventory API flow of use can generally follow the sequence below\n\n\n#### Call ONAP to discover what available services it has in the service inventory by listing them\n\n```\ncurl -X GET \"http://serverRoot:30274/nbi/api/v4/service/\" -H \"accept: application/json;charset=utf-8\"\n```\n#### Using the id returned from the list of Service instances, drill into any specific Service instance you want to view using\n\n\n\n```\ncurl -X GET \"http://serverRoot:30274/nbi/api/v4/service/0ec83a1f-51e7-44e7-b773-3f37ddb937cd\" -H \"accept: application/json;charset=utf-8\"\n```\n#### Example Response Values\n```\n{\"id\":\"c96fb8ec-8552-4956-8a8d-65680aaa57cc\",\"name\":\"Service_1234\",\"@type\":\"serviceONAP\",\"supportingResource\":[],\"serviceSpecification\":{\"id\":\"462f84e5-f0e5-44c5-ab95-38fb4bf77064\",\"name\":\"CS Template Name\",\"invariantUUID\":\"88dcb2f0-085b-4548-8b93-0882e37d25d8\",\"@type\":\"ONAPservice\"},\"state\":\"active\",\"relatedParty\":{\"role\":\"ONAPcustomer\",\"id\":\"CustomerId1\"},\"type\":\"service-instance\"}\r\n\n```\n\n"
  17   version: 4.1.0
  18   title: ServiceInventory API
  19   contact:
  20     name: ONAP
  21     url: 'https://onap.readthedocs.io'
  22     email: onap-discuss@lists.onap.org
  23   license:
  24     name: Apache 2.0
  25     url: 'http://www.apache.org/licenses/LICENSE-2.0'
  26   x-planned-retirement-date: '205001'
  27   x-component: NBI
  28   x-logo:
  29     url: /redoc/logo.png
  30     backgroundColor: '#FFFFFF'
  31 host: 'serverRoot:30274'
  32 basePath: /nbi/api/v4
  33 schemes:
  34   - http
  35   - https
  36 produces:
  37   - application/json;charset=utf-8
  38 tags:
  39   - name: Service
  40     description: Provided by NBI
  41   - name: Notification
  42     description: >-
  43       provided by subscriber, which MUST has been registered by creating a Hub
  44       ressource on NBI
  45 paths:
  46   x-interface:
  47     api-version: 4.1.0
  48     last-mod-release: Frankfurt
  49   /service:
  50     get:
  51       tags:
  52         - Service
  53       produces:
  54         - application/json;charset=utf-8
  55       operationId: service_Find
  56       summary: List services
  57       description: >-
  58         This operation list service entities.
  59
  60         Attribute selection is restricted.
  61
  62         fields attribute may be used to filter retrieved attribute(s) for each
  63         service
  64       deprecated: false
  65       parameters:
  66         - name: relatedParty.id
  67           required: false
  68           in: query
  69           description: ''
  70           type: string
  71         - name: serviceSpecification.id
  72           required: false
  73           in: query
  74           description: ''
  75           type: string
  76         - name: serviceSpecification.name
  77           required: false
  78           in: query
  79           description: ''
  80           type: string
  81         - name: id
  82           required: false
  83           in: query
  84           description: ''
  85           type: string
  86         - name: fields
  87           required: false
  88           in: query
  89           description: ''
  90           type: string
  91       responses:
  92         '200':
  93           description: Ok
  94           schema:
  95             type: array
  96             items:
  97               $ref: '#/definitions/ListService'
  98   '/service/{id}':
  99     get:
 100       tags:
 101         - Service
 102       produces:
 103         - application/json;charset=utf-8
 104       operationId: service_Get
 105       summary: Retrieve a service
 106       description: |-
 107         This operation retrieves a service entity.
 108         Attribute selection is enabled for all first level attributes.
 109       deprecated: false
 110       parameters:
 111         - name: id
 112           required: true
 113           in: path
 114           type: string
 115       responses:
 116         '200':
 117           description: Ok
 118           schema:
 119             $ref: '#/definitions/Service'
 120   /notification:
 121     post:
 122       tags:
 123         - Notification
 124       consumes:
 125         - application/json;charset=utf-8
 126       produces:
 127         - application/json;charset=utf-8
 128       operationId: notification_Create
 129       summary: NBI will send notification to this operation provided by subscribers
 130       description: ''
 131       deprecated: false
 132       parameters:
 133         - name: Notification
 134           required: true
 135           in: body
 136           description: ''
 137           schema:
 138             $ref: '#/definitions/Notification'
 139       responses:
 140         '201':
 141           description: Created
 142           schema:
 143             $ref: '#/definitions/Notification'
 144 definitions:
 145   eventType:
 146     description: The Event Type
 147     type: string
 148     enum:
 149       - ServiceCreationNotification
 150       - ServiceAttributeValueChangeNotification
 151       - ServiceRemoveNotification
 152   ErrorRepresentation:
 153     description: This class is used to describe error.
 154     required:
 155       - code
 156       - reason
 157     type: object
 158     properties:
 159       code:
 160         description: Application related code (as defined in the API or from a common list)
 161         type: integer
 162         format: int32
 163       reason:
 164         description: >-
 165           Text that explains the reason for error. This can be shown to a client
 166           user.
 167         type: string
 168       message:
 169         description: >-
 170           Text that provide more details and corrective actions related to the
 171           error. This can be shown to a client user.
 172         type: string
 173       status:
 174         description: http error code extension like 400-2
 175         type: string
 176       referenceError:
 177         description: url pointing to documentation describing the error
 178         type: string
 179       '@type':
 180         description: The class type of a REST resource.
 181         type: string
 182       '@schemaLocation':
 183         description: it provides a link to the schema describing a REST resource.
 184         type: string
 185   Service:
 186     description: Instantiated service (service_instance) in AAI
 187     type: object
 188     properties:
 189       id:
 190         description: Unique identifier of the service - Valued with service-instance-id
 191         type: string
 192       href:
 193         description: |-
 194           Reference of the service
 195           Not managed in Beijing release
 196         type: string
 197       name:
 198         description: Name of the service - Valued with service-instance-name
 199         type: string
 200       type:
 201         description: Service type - valued with 'service-instance'
 202         type: string
 203       state:
 204         description: State of the service.
 205         type: string
 206       '@type':
 207         description: >-
 208           This attribute allows to dynamically extends TMF class. Not used in
 209           Beijing release.
 210         type: string
 211       '@baseType':
 212         description: Not managed in Beijing release
 213         type: string
 214       '@schemaLocation':
 215         description: Not managed in Beijing release
 216         type: string
 217       serviceSpecification:
 218         $ref: '#/definitions/ServiceSpecificationRef'
 219       characteristic:
 220         type: array
 221         items:
 222           $ref: '#/definitions/ServiceCharacteristic'
 223       supportingResource:
 224         type: array
 225         items:
 226           $ref: '#/definitions/SupportingResource'
 227       relatedParty:
 228         type: array
 229         items:
 230           $ref: '#/definitions/RelatedPartyRef'
 231   ServiceSpecificationRef:
 232     description: >-
 233       Service specification reference: ServiceSpecification of this service
 234       (catalog information)
 235     type: object
 236     properties:
 237       id:
 238         description: >-
 239           Unique identifier of the service specification. valued to
 240           model-version-id
 241         type: string
 242       href:
 243         description: |-
 244           Reference of the service specification.
 245           not managed in Beijing release.
 246         type: string
 247       name:
 248         description: Name of the required service specification
 249         type: string
 250       version:
 251         description: |-
 252           Service specification version.
 253           Not managed in Beijing release
 254         type: string
 255       '@referredType':
 256         description: >-
 257           This attribute allows to dynamically extends TMF class. Valued with
 258           'ONAPservice'. We used this features to add following attribute:
 259           invariantUUID
 260         type: string
 261       '@schemaLocation':
 262         description: Not managed in Beijing release
 263         type: string
 264       invariantUUID:
 265         description: >-
 266           Additional attribute (not in the TMF API) - extended through
 267           @referredType - model-invariant-id
 268         type: string
 269   ServiceCharacteristic:
 270     description: |-
 271       A list of name value pairs that define the service characteristics
 272       Not managed in Beijing release.
 273     required:
 274       - name
 275     type: object
 276     properties:
 277       name:
 278         description: |-
 279           Name of the characteristic
 280           Not managed in Beijing release.
 281         type: string
 282       valueType:
 283         description: |-
 284           Type of value for this characteristic.
 285           Not managed in Beijing release.
 286         type: string
 287       value:
 288         $ref: '#/definitions/Value'
 289   SupportingResource:
 290     description: >-
 291       Supporting resource - A supportingResource will be retrieved for each
 292       relationship of the relationship-list where related-link describe a vnf
 293     type: object
 294     properties:
 295       id:
 296         description: Unique identifier of the supporting resource - Valued to vnf-id
 297         type: string
 298       href:
 299         description: Reference of the supporting resource
 300         type: string
 301       role:
 302         description: Not managed in Beijing release.
 303         type: string
 304       name:
 305         description: Name of the supporting resource - Valued with vnf_-name
 306         type: string
 307       '@referredType':
 308         description: "This attribute allows to dynamically extends TMF class. Valued with 'ONAP resource'. We used this features to add following attributes:\n    status\t\n    modelInvariantId\n   modelVersionId\n   modelCustomisationId"
 309         type: string
 310       '@schemaLocation':
 311         description: Not managed in Beijing release.
 312         type: string
 313       status:
 314         description: >-
 315           Additional attribute (not in the TMF API) - extended through
 316           @referredType - valued with prov-status
 317         type: string
 318       modelInvariantId:
 319         description: >-
 320           Additional attribute (not in the TMF API) - extended through
 321           @referredType - valued with model-invariant-id
 322         type: string
 323       modelVersionId:
 324         description: >-
 325           Additional attribute (not in the TMF API) - extended through
 326           @referredType - valued with model-verson-id
 327         type: string
 328       modelCustomisationId:
 329         description: >-
 330           Additional attribute (not in the TMF API) - extended through
 331           @referredType - valued with model-customisation-id
 332         type: string
 333   RelatedPartyRef:
 334     description: >-
 335       RelatedParty reference. A related party defines party or party role linked
 336       to a specific entity.
 337     type: object
 338     properties:
 339       id:
 340         description: Unique identifier of a related party
 341         type: string
 342       href:
 343         description: |-
 344           Reference of a related party.
 345           Not filled in Beijing release.
 346         type: string
 347       role:
 348         description: |-
 349           Role played by the related party.
 350           Filled with 'ONAPcustomer'
 351         type: string
 352       '@referredType':
 353         description: Not managed in the Beijing release.
 354         type: string
 355   Value:
 356     description: |-
 357       Structure used to describe characteristic value.
 358       Not managed in Beijing release.
 359     type: object
 360     properties:
 361       '@type':
 362         description: Not managed in Beijing release.
 363         type: string
 364       '@schemaLocation':
 365         description: Not managed in Beijing release.
 366         type: string
 367       serviceCharacteristicValue:
 368         description: Not managed in Beijing release.
 369         type: string
 370   ListRelatedPartyRef:
 371     description: This class is used to structure list of service(s) retrieved
 372     type: object
 373     properties:
 374       id:
 375         description: Unique identifier of a related party
 376         type: string
 377       role:
 378         description: >-
 379           Role played by the related party - only role “ONAPcustomer” is managed
 380           in Beijing release.
 381         type: string
 382   ListServiceSpecificationRef:
 383     description: This class is used to structure list of service(s) retrieved
 384     type: object
 385     properties:
 386       id:
 387         description: Unique identifier of the service specification
 388         type: string
 389       name:
 390         description: Name of the required service specification
 391         type: string
 392   ListService:
 393     description: This class is used to structure list of service(s) retrieved
 394     type: object
 395     properties:
 396       id:
 397         description: Unique identifier of the service
 398         type: string
 399       name:
 400         description: Name of the service
 401         type: string
 402       serviceSpecification:
 403         $ref: '#/definitions/ListServiceSpecificationRef'
 404       relatedParty:
 405         $ref: '#/definitions/ListRelatedPartyRef'
 406   ServiceInventoryEvent:
 407     description: Structure for a service inventory event notification
 408     required:
 409       - id
 410       - href
 411       - name
 412       - type
 413       - state
 414       - relatedParty
 415     type: object
 416     properties:
 417       id:
 418         description: The Service Instance Id
 419         type: string
 420       href:
 421         description: A reference to the service inventory
 422         type: string
 423       name:
 424         description: The name of the Service Instance
 425         type: string
 426       type:
 427         description: 'The type of event, service-instance'
 428         type: string
 429       state:
 430         description: The state of the service instance
 431         type: string
 432       relatedParty:
 433         $ref: '#/definitions/RelatedPartyRef'
 434   Notification:
 435     description: Notification structure for a service notification
 436     required:
 437       - eventId
 438       - eventDate
 439       - eventType
 440       - event
 441     type: object
 442     properties:
 443       eventId:
 444         description: ''
 445         type: string
 446       eventDate:
 447         description: ''
 448         type: string
 449         format: date-time
 450       eventType:
 451         $ref: '#/definitions/eventType'
 452       event:
 453         $ref: '#/definitions/ServiceInventoryEvent'