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