docs/offeredapis/offeredapis.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0
   2    International License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4 .. Copyright 2018 ORANGE
   5 .. _offeredapis:
   6
   7
   8 ============
   9 Offered APIs
  10 ============
  11 ************
  12 Introduction
  13 ************
  14
  15 NBI stands for NorthBound Interface. It brings to ONAP a set of API that can
  16 be used by external systems as BSS for example. These API are based on
  17 **TMF API**.
  18
  19 *******************************************
  20 Global NBI architecture for Honolulu release
  21 *******************************************
  22
  23 Following illustration provides a global view about **NBI** architecture,
  24 integration with other ONAP components and API resource/operation provided.
  25
  26 .. image:: ../images/onap_nbi_dublin.jpg
  27    :width: 800px
  28
  29 ************
  30 API Endpoint
  31 ************
  32
  33 Since Frankfurt, in an OOM ONAP deployment context:
  34
  35 https://nbi.api.simpledemo.onap.org:30274/nbi/api/v4
  36
  37 Locally, for dev and testing purpose:
  38
  39 http://localhost:8080/nbi/api/v4
  40
  41 ***********
  42 API Version
  43 ***********
  44
  45 APIs are described with a  state version with "v" following the API Name,
  46 e.g.:  ``nbi/api/v4/productOrder``.
  47 The schema associated with a REST API must have its version number aligned
  48 with that of the REST API.
  49
  50 The version number has major, minor and revision numbers. E.g. v1.0.0
  51 The version number (without the revision number) is held in the URI.
  52
  53 The major version number is incremented for an incompatible change.
  54 The minor version number is incremented for a compatible change.
  55 For minor modifications of the API, version numbering must not be updated,
  56 provided the following  backward compatibility rules are respected:
  57
  58 - New elements in a data type must be optional (``minOccurs=0``)
  59 - Changes in the cardinality of an attribute in a data type must be from
  60   mandatory to optional or from lower to greater
  61 - New attributes defined in an element must be optional (absence of
  62   ``use="required"``).
  63 - If new enumerated values are included, the former ones and its meaning must
  64   be kept.
  65 - If new operations are added, the existing operations must be kept
  66 - New parameters added to existing operations must be optional and existing
  67   parameters must be kept
  68
  69 For major modifications of the API, not backward compatible and forcing client
  70 implementations to be changed, the version number must be updated.
  71
  72 *********
  73 API Table
  74 *********
  75
  76 .. |pdf-icon| image:: images/pdf.png
  77               :width: 40px
  78
  79 .. |swagger-icon| image:: images/swagger.png
  80                   :width: 40px
  81
  82
  83 .. |swaggerUI-icon| image:: images/swaggerUI.png
  84                     :width: 40px
  85
  86 .. |html-icon| image:: images/html.png
  87                :width: 40px
  88
  89 .. |plantuml-icon| image:: images/uml.jpg
  90                   :width: 40px
  91
  92 .. |postman-icon| image:: images/postman.png
  93                   :width: 40px
  94
  95 .. |xml-icon| image:: images/text_xml.png
  96                   :width: 40px
  97
  98 .. csv-table::
  99    :header: "API", "|swagger-icon|", "|swagger-icon|", "|plantuml-icon|", "|xml-icon|"
 100    :widths: 10,5,5,5,5
 101
 102    " ", "json file", "yaml file", "plant UML file", "xml schemas"
 103    "hub", ":download:`link <api_hub/swagger.json>`", ":download:`link <api_hub/swagger.yaml>`", ":download:`link <api_hub/api.plantuml>`", ":download:`link <api_hub/model.xsd>`"
 104    "serviceCatalog", ":download:`link <api_serviceCatalog/swagger.json>`", ":download:`link <api_serviceCatalog/swagger.yaml>`", ":download:`link <api_serviceCatalog/api.plantuml>`", ":download:`link <api_serviceCatalog/model.xsd>`"
 105    "serviceInventory", ":download:`link <api_serviceInventory/swagger.json>`", ":download:`link <api_serviceInventory/swagger.yaml>`", ":download:`link <api_serviceInventory/api.plantuml>`", ":download:`link <api_serviceInventory/model.xsd>`"
 106    "serviceOrder", ":download:`link <api_serviceOrder/swagger.json>`", ":download:`link <api_serviceOrder/swagger.yaml>`", ":download:`link <api_serviceOrder/api.plantuml>`", ":download:`link <api_serviceOrder/model.xsd>`"
 107    "status", ":download:`link <api_status/swagger.json>`", ":download:`link <api_status/swagger.yaml>`", ":download:`link <api_status/api.plantuml>`", ":download:`link <api_status/model.xsd>`"
 108
 109 ***********************
 110 API ReDoc Documentation
 111 ***********************
 112
 113 * :doc:`API hub <redoc/api_hub>`
 114 * :doc:`Service Catalog <redoc/api_serviceCatalog>`
 115 * :doc:`Service Inventory <redoc/api_serviceInventory>`
 116 * :doc:`Service Order <redoc/api_serviceOrder>`
 117 * :doc:`Status <redoc/api_status>`
 118
 119
 120 ***************
 121 API Description
 122 ***************
 123
 124 --------------
 125 serviceCatalog
 126 --------------
 127
 128 This API is based from TMF633 serviceCatalog. Only high level information
 129 is provided - Swagger is documented.
 130
 131 Only ``serviceSpecification`` resource is provided.
 132 Information are retrieved in **SDC** (and in TOSCA file)
 133
 134 Only characteristics at service level will be retrieved in ONAP TOSCA file.
 135 For example if an ONAP service is composed of VNF and the VF module, the
 136 ``serviceSpecification`` resource will only feature characteristic described in
 137 the ONAP service TOSCA model and not attributes in the TOSCA files for VNF
 138 or VF module.
 139
 140 Only *basic* service characteristics will be managed in this release. By
 141 *basic* we mean string, boolean, integer parameter type and we do not manage
 142 *map* or *list* parameter type.
 143
 144
 145 **GET serviceSpecification(list)**
 146
 147 Example: ``GET /nbi/api/v4/serviceSpecification/
 148 ?category=NetworkService&distributionStatus=DISTRIBUTED``
 149
 150 It is possible to retrieve a list of ``serviceSpecification`` (get by list).
 151
 152 Only attributes ``category`` and ``distributionStatus`` are available for
 153 ``serviceSpecification`` filtering. It is possible to select retrieved
 154 attributes using fields attribute.
 155
 156 If no ``serviceSpecification`` matches, an empty list is send back.
 157
 158 **GET service Specification (id)**
 159
 160 Example: ``GET /nbi/api/v4/serviceSpecification/{uuid}``
 161
 162 It is use to retrieve one ``serviceSpecification`` - all available information
 163 are retrieved (see Swagger for description)
 164
 165 **GET service Specification Schema (id)**
 166
 167 Example:
 168 ``GET /nbi/api/v4/serviceSpecification/{uuid}/specificationInputSchema``
 169
 170 It is use to retrieve one  input schema from the tosca file stored in **NBI**
 171 - all available information are retrieved (see Swagger for description)
 172
 173 **POST service Specification**
 174
 175 Example:
 176
 177 ``POST /nbi/api/v4/serviceSpecification``
 178
 179 This operation creates a ``serviceSpecification`` in catalog (see Swagger for description)
 180 It is used to provide a consistent way of on-boarding third party services to SDC via External API
 181
 182 Only *primitive type* service characteristics are supported as part of this release. Further enhancements
 183 need to be made on other modules of ONAP for ensuring e2e automation of third party services.
 184
 185 ----------------
 186 serviceInventory
 187 ----------------
 188
 189 This API is based from TMF638 serviceInventory. Only high level information
 190 is provided - Swagger is documented.
 191
 192 This API retrieves service(s) in the **A&AI** inventory. Only following
 193 attributes will be retrieve in service inventory: ``id``, ``name``, ``state``
 194 and ``type``
 195
 196 **GET Service Inventory (list)**
 197
 198 Example: ``GET /nbi/api/v4/service/?relatedParty.id=Pontus``
 199
 200 GET (by list) allows to request with following criteria (all optional) :
 201
 202 *   ``id`` (id of the service instance) - id of the service instance
 203     (inventory)
 204 *   ``serviceSpecification.id`` - id of the service specification (catalog)
 205 *   ``serviceSpecification.name`` - name of the service specification (catalog)
 206 *   ``relatedParty.id`` - id of the (**A&AI**) customer - if not filled we use
 207     *generic* customer
 208
 209 if no service matches, an empty list is send back.
 210
 211 1. If a request is send without any parameter, we'll retrieve the list of
 212    service-instance for the *generic* customer
 213 2. If only customer parameter is filled (``relatedParty.id`` +
 214    role= relatedParty'ONAPcustomer') we'll retrieve the list of
 215    service-instance for this customer
 216 3. If serviceSpecification.id or name is filled we'll retrieve the list of
 217    Service instance (from this service specification) - We'll use the customer
 218    id if provided (with Role='ONAPcustomer) or generic if no customer id
 219    provided
 220
 221 **GET Service Inventory (id)**
 222
 223 Example: ``GET /nbi/api/v4/service/{id}`` When querying for a specific service
 224 instance id, no additional filters are required.
 225
 226 The Service Inventory API will retrieve the service instance data from A&AI
 227 using the nodes query with the service instance id as the key.
 228 ``relatedParty.id`` + ``serviceSpecification.name`` are added to the response
 229 based on the A&AI service instance url.
 230
 231 ------------
 232 serviceOrder
 233 ------------
 234
 235 This API is based from  TMF641 serviceOrder. Only high level information
 236 is provided - Swagger is documented.
 237
 238 It is possible to use POST operation to create new ``serviceOrder`` in **NBI**
 239 and triggers service provisioning. GET operation is also available to retrieve
 240 one service order by providing id or a list of service order. For this release,
 241 only a subset of criteria is available:
 242
 243 * ``externalId``
 244 * ``state``
 245 * ``description``
 246 * ``orderDate.gt`` (orderDate must be greater - after -than)
 247 * ``orderDate.lt`` (orderDate must be lower-before - than)
 248 * ``fields`` - attribute used to filter retrieved attributes (if needed) and
 249   also for sorted SO
 250 * ``offset`` and ``limit`` are used for pagination purpose
 251
 252 ServiceOrder will manage following ``actionItem`` action:
 253
 254 * ``add`` - a new service will be created
 255 * ``delete`` - an existing service will be deleted
 256 * ``change`` - an existing service will be deleted and then created with new
 257   attribute value
 258
 259 **Prerequisites & assumptions**
 260
 261 * Cloud & tenant information MUST BE defined in the external API property file
 262 * Management of ONAP customer for add service action
 263
 264 With the current version of APIs used from **SO** and **A&AI** we need to
 265 manage a *customer*. This customer concept is confusing with Customer BSS
 266 concept. We took the following rules to manage the *customer* information:
 267
 268 * It could be provided through a ``serviceOrder`` in the service Order a
 269   ``relatedParty`` with role ``ONAPcustomer`` should be provided in the
 270   ``serviceOrder`` header (we will not consider in this release the party
 271   at item level). External API component will check if this customer exists
 272   and create it in **A&AI** if not.
 273 * If no ``relatedParty`` is provided, the service will be affected to
 274   ``generic customer`` (dummy customer) - we assume this ``generic customer``
 275   always exists.
 276 * Additionally **NBI** will create in **A&AI** the service-type if it did not
 277   exists for the customer
 278
 279 **ServiceOrder management in NBI will support 2 modes:**
 280
 281 * E2E integration - **NBI** calls **SO** API to perform an End-To-end
 282   integration
 283 * Service-level only integration - **NBI** will trigger only **SO** request at
 284   serviceInstance level. **SO** prerequisite: **SO** must be able to find a
 285   BPMN to process service fulfillment (integrate VNF, VNF activation in
 286   **SDNC**, VF module
 287
 288 The choice of the mode is done in NBI depending on information retrieved in
 289 **SDC**. If the serviceSpecification is within a Category "E2E Service" ,
 290 **NBI** will use E2E **SO** API, if not only API at service instance level
 291 will be used.
 292
 293 There is no difference or specific expectation in the service order API used
 294 by **NBI** user.
 295
 296 **ServiceOrder tracking**
 297
 298 State management: States are only managed by ServiceOrder component and could
 299 not be updated from north side via API.
 300 Accordingly to service order item fulfillment progress, order item state are
 301 updated. Order state is automatically updated based on item state.
 302 Additionnally to this state, **NBI** provided a completion percent progress to
 303 have detailled information about order progress.
 304 Order Message are retrieved in the ``GET serviceOrder`` to provide **NBI** used
 305 addtionnal information about ``serviceOrder`` management.
 306
 307 **Notification:**
 308
 309 It is possible for an external system to subscribe to service order
 310 notifications. 3 events are managed:
 311
 312 * A new service order is created in **NBI**
 313 * A service order state changes
 314 * A service order item state changes
 315
 316 It is also possible to subscribe to **AAI** and **SDC** notifications via
 317 **NBI**.
 318 4 events are managed:
 319
 320 * A new service is created in  **AAI***
 321 * A service attribute value is changed in **AAI**
 322 * A service is removed in **AAI**
 323 * A service specification is distributed in **SDC**
 324
 325 These 7 events have distinct notification allowing any system to subscribe to
 326 one, two or all notification types.
 327
 328 The implementation will be split in 2 components:
 329
 330 * A HUB resource must be managed within the NBI/serviceOrder API. This HUB
 331   resource allows system to subscribe to **NBI** notification
 332 * An Event API must be available at listener side in order to be able to
 333   receive Listener (when event occurs). **NBI** will be upgraded to use this
 334   API as client - **NBI** will shoot ``POST listener/``
 335
 336 The following diagram illustrates such notification flow:
 337
 338 .. image:: images/notification.jpg
 339    :width: 800px
 340
 341 **East-west interaction of ONAP instances through External API**
 342
 343 Operator's SO component will talk to service provider's external API component
 344 through its own external API component.
 345
 346 External API support two methods of posting a Service Order or registering for
 347 Hub.
 348
 349 1. If the incoming request is per current implementation (no additional headers
 350 ) then no changes will be made. The request will be serviced per BAU flow.
 351 2. If the incoming request has additional *Target* header parameters, External
 352 API will identify that the request has to be relayed to another ONAP instance
 353 and route the request accordingly.
 354
 355 Target parameter: The public endpoint url for target ONAP instance's External
 356 API, for instance
 357 http://externalDomain/nbi/api/vX
 358
 359 * For posting service order and getting service order status, the request will
 360   be relayed to target (service provider's External API) as-is. These are
 361   synchronous requests and operator's External API will wait for response from
 362   the target and relay it back to original calling system (operator's SO).
 363 * For Hub API, there is an additional step required. The listener from calling
 364   system (operator's SO) will be replaced with External APIs own listener.
 365   A mapping of registered subscriber and its original listener will be
 366   maintained in External API's DB. Operator's External API will relay the Hub
 367   API call to service provider's External API. The service provider's External
 368   API will register operator's External API as a listener.
 369 * After SO processing in service provider's ONAP is completed (irrespective of
 370   status - reject, success, fail etc), service provider's External API will
 371   notify the operator's External API about request completion. Operator's
 372   External API will look-up for registered subscriber and its original listener
 373   (operator's SO) and relay the message.
 374
 375 Operator's Service Orchestrator will invoke its own External API component and
 376 add SP Partner URL in the header. After receiving an acknowledgement for
 377 Service Order request, the SO component will register with External API's hub
 378 and provide its listener for processing callback events.
 379
 380 Technical information about **East-west interaction exercise** design
 381 specification and API Flow illustration (with example messages) could be found
 382 here:
 383
 384 https://wiki.onap.org/download/attachments/8227019/CCVPN%20Phase%202%20HLD.docx?api=v2
 385
 386
 387 ***************
 388 Developer Guide
 389 ***************
 390
 391 Technical information about **NBI** (dependencies, configuration, running &
 392 testing) could be found here:
 393 :doc:`NBI_Developer_Guide <../architecture/NBI_Developer_Guide>`
 394
 395 API Flow illustration (with example messages) is described in this document:
 396 :download:`nbicallflow.pdf <pdf/nbicallflow.pdf>`