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
   6
   7 ============
   8 Offered APIs
   9 ============
  10 ************
  11 Introduction
  12 ************
  13
  14 NBI stands for NorthBound Interface. It brings to ONAP a set of API that can
  15 be used by external systems as BSS for example. These API are based on
  16 **TMF API**.
  17
  18 **********************************************
  19 Global NBI architecture for Casablanca release
  20 **********************************************
  21
  22 Following illustration provides a global view about **NBI** architecture,
  23 integration with other ONAP components and API resource/operation provided.
  24
  25 .. image:: images/ONAP_External_ID_Casablanca.jpg
  26    :width: 800px
  27
  28 ***********
  29 API Version
  30 ***********
  31
  32 APIs are described with a  state version with “v” following the API Name,
  33 e.g.:  ``nbi/api/v3/productOrder``.
  34 The schema associated with a REST API must have its version number aligned
  35 with that of the REST API.
  36
  37 The version number has major, minor and revision numbers. E.g. v1.0.0
  38 The version number (without the revision number) is held in the URI.
  39
  40 The major version number is incremented for an incompatible change.
  41 The minor version number is incremented for a compatible change.
  42 For minor modifications of the API, version numbering must not be updated,
  43 provided the following  backward compatibility rules are respected:
  44
  45 - New elements in a data type must be optional (``minOccurs=0``)
  46 - Changes in the cardinality of an attribute in a data type must be from
  47   mandatory to optional or from lower to greater
  48 - New attributes defined in an element must be optional (absence of
  49   ``use=”required”``).
  50 - If new enumerated values are included, the former ones and its meaning must
  51   be kept.
  52 - If new operations are added, the existing operations must be kept
  53 - New parameters added to existing operations must be optional and existing
  54   parameters must be kept
  55
  56 For major modifications of the API, not backward compatible and forcing client
  57 implementations to be changed, the version number must be updated.
  58
  59 *********
  60 API Table
  61 *********
  62
  63 .. |pdf-icon| image:: images/pdf.png
  64               :width: 40px
  65
  66 .. |swagger-icon| image:: images/swagger.png
  67                   :width: 40px
  68
  69
  70 .. |swaggerUI-icon| image:: images/swaggerUI.png
  71                     :width: 40px
  72
  73 .. |html-icon| image:: images/html.png
  74                :width: 40px
  75
  76 .. |plantuml-icon| image:: images/uml.jpg
  77                   :width: 40px
  78
  79 .. |postman-icon| image:: images/postman.png
  80                   :width: 40px
  81
  82 .. csv-table::
  83    :header: "API", "|swagger-icon|", "|html-icon|", "|plantuml-icon|", "|swagger-icon|", "|postman-icon|", "|pdf-icon|"
  84    :widths: 10,5,5,5,5,5,5
  85
  86    " ", "json file", "html doc", "plantUML doc", "Swagger Editor", "Postman Collection", "pdf doc"
  87    "serviceCatalog", ":download:`link <swaggers/serviceCatalog_3_0_0.json>`", ":download:`link <serviceCatalog/documentation.html>`", ":download:`link <serviceCatalog/apiServiceCatalog.plantuml>`", "coming", "coming", "coming"
  88    "serviceInventory", ":download:`link <swaggers/serviceInventory_3_0_0.json>`", ":download:`link <serviceInventory/documentation.html>`", ":download:`link <serviceInventory/apiServiceInventory.plantuml>`", "coming", "coming", "coming"
  89    "serviceOrder", ":download:`link <swaggers/serviceOrder_3_0_0.json>`", ":download:`link <serviceOrder/documentation.html>`", ":download:`link <serviceOrder/apiServiceOrder.plantuml>`", "coming", ":download:`link <postman/ONAPBeijingServiceOrderDoc.postman_collection.json>`", "coming"
  90
  91
  92 ***************
  93 API Description
  94 ***************
  95
  96 --------------
  97 serviceCatalog
  98 --------------
  99
 100 This API is based from TMF633 serviceCatalog. Only high level information
 101 is provided - Swagger is documented.
 102
 103 Only ``serviceSpecification`` resource is provided.
 104 Information are retrieved in **SDC** (and in TOSCA file)
 105 - Only GET operation is provided - this API does not update **SDC**.
 106
 107 Only characteristics at service level will be retrieved in ONAP TOSCA file.
 108 For example if an ONAP service is composed of VNF and the VF module, the
 109 ``serviceSpecification`` resource will only feature characteristic described in
 110 the ONAP service TOSCA model and not attributes in the TOSCA files for VNF
 111 or VF module.
 112
 113 Only *basic* service characteristics will be managed in this release. By
 114 *basic* we mean string, boolean, integer parameter type and we do not manage
 115 *map* or *list* parameter type.
 116
 117
 118 **GET serviceSpecification(list)**
 119
 120 Example: ``GET /nbi/api/v3/serviceSpecification/
 121 ?category=NetworkService&distributionStatus=DISTRIBUTED``
 122
 123 It is possible to retrieve a list of ``serviceSpecification`` (get by list).
 124
 125 Only attributes ``category`` and ``distributionStatus`` are available for
 126 ``serviceSpecification`` filtering. It is possible to select retrieved
 127 attributes using fields attribute.
 128
 129 If no ``serviceSpecification`` matches, an empty list is send back.
 130
 131 **GET service Specification (id)**
 132
 133 Example: ``GET /nbi/api/v3/serviceSpecification/{uuid}``
 134
 135 It is use to retrieve one ``serviceSpecification`` - all available information
 136 are retieved (see Swagger for description)
 137
 138 ----------------
 139 serviceInventory
 140 ----------------
 141
 142 This API is based from TMF638 serviceInventory. Only high level information
 143 is provided - Swagger is documented.
 144
 145 This API retrieves service(s) in the **A&AI** inventory. Only following
 146 attributes will be retrieve in service inventory: ``id``, ``name``, ``state``
 147 and ``type``
 148
 149 **GET Service Inventory (list)**
 150
 151 Example: ``GET /nbi/api/v3/service/?relatedParty.id=Pontus``
 152
 153 GET (by list) allows to request with following criteria (all optional) :
 154
 155 *   ``id`` (id of the service instance) - id of the service instance
 156     (inventory)
 157 *   ``serviceSpecification.id`` - id of the service specification (catalog)
 158 *   ``serviceSpecification.name`` - name of the service specification (catalog)
 159 *   ``relatedParty.id`` - id of the (**A&AI**) customer - if not filled we use
 160     *generic* customer
 161
 162 if no service matches, an empty list is send back.
 163
 164 1. If a request is send without any parameter, we’ll retrieve the list of
 165    service-instance for the *generic* customer
 166 2. If only customer parameter is filled (``relatedParty.id`` +
 167    role= relatedParty’ONAPcustomer’) we’ll retrieve the list of
 168    service-instance for this customer
 169 3. If serviceSpecification.id or name is filled we’ll retrieve the list of
 170    Service instance (from this service specification) – We’ll use the customer
 171    id if provided (with Role=’ONAPcustomer) or generic if no customer id
 172    provided
 173
 174 **GET Service Inventory (id)**
 175
 176 Example: ``GET /nbi/api/v3/service/{uuid}`` but ``customerId`` &
 177 ``serviceSpecification.id`` must passed in requested parameters
 178
 179
 180 Because of **A&AI** capability, additionally to the service id, customer id
 181 and ``serviceSpecification.id`` or ``serviceSpecification.name`` must be
 182 supplied. If the customer id is not supplied, External API will use *generic*
 183 customer
 184
 185 ------------
 186 serviceOrder
 187 ------------
 188
 189 This API is based from  TMF641 serviceOrder. Only high level information
 190 is provided - Swagger is documented.
 191
 192 It is possible to use POST operation to create new ``serviceOrder`` in **NBI**
 193 and triggers service provisioning. GET operation is also available to retrieve
 194 one service order by providing id or a list of service order. For this release,
 195 only a subset of criteria is available:
 196
 197 • ``externalId``
 198 • ``state``
 199 • ``description``
 200 • ``orderDate.gt`` (orderDate must be greater – after -than)
 201 • ``orderDate.lt`` (orderDate must be lower-before - than)
 202 • ``fields`` – attribute used to filter retrieved attributes (if needed) and
 203   also for sorted SO
 204 • ``offset`` and ``limit`` are used for pagination purpose
 205
 206 ServiceOrder will manage following ``actionItem`` action:
 207
 208 • ``add`` - a new service will be created
 209 • ``delete`` - an existing service will be deleted
 210 • ``change`` - an existing service will be deleted and then created with new
 211   attribute value
 212
 213 **Prerequisites & assumptions**
 214
 215 • Cloud & tenant information MUST BE defined in the external API property file
 216 • Management of ONAP customer for add service action
 217
 218 With the current version of APIs used from **SO** and **A&AI** we need to
 219 manage a *customer*. This customer concept is confusing with Customer BSS
 220 concept. We took the following rules to manage the *customer* information:
 221
 222 • It could be provided through a ``serviceOrder`` in the service Order a
 223   ``relatedParty`` with role ``ONAPcustomer`` should be provided in the
 224   ``serviceOrder`` header (we will not consider in this release the party
 225   at item level). External API component will check if this customer exists
 226   and create it in **A&AI** if not.
 227 • If no ``relatedParty`` is provided, the service will be affected to
 228   ``generic customer`` (dummy customer) – we assume this ``generic customer``
 229   always exists.
 230 • Additionally **NBI** will create in **A&AI** the service-type if it did not
 231   exists for the customer
 232
 233 **ServiceOrder management in NBI will support 2 modes:**
 234
 235 • E2E integration - **NBI** calls **SO** API to perform an End-To-end
 236   integration
 237 • Service-level only integration - **NBI** will trigger only **SO** request at
 238   serviceInstance level. **SO** prerequisite: **SO** must be able to find a
 239   BPMN to process service fulfillment (integrate VNF, VNF activation in
 240   **SDNC**, VF module
 241
 242 The choice of the mode is done in NBI depending on information retrieved in
 243 **SDC**. If the serviceSpecification is within a Category “E2E Service” ,
 244 **NBI** will use E2E **SO** API, if not only API at service instance level
 245 will be used.
 246
 247 There is no difference or specific expectation in the service order API used
 248 by **NBI** user.
 249
 250 **ServiceOrder tracking**
 251
 252 State management: States are only managed by ServiceOrder component and could
 253 not be updated from north side via API.
 254 Accordingly to service order item fulfillment progress, order item state are
 255 updated. Order state is automatically updated based on item state.
 256 Additionnally to this state, **NBI** provided a completion percent progress to
 257 have detailled information about order progress.
 258 Order Message are retrieved in the ``GET serviceOrder`` to provide **NBI** used
 259 addtionnal information about ``serviceOrder`` management.
 260
 261 **Notification:**
 262
 263 It is possible for an external system to subscribe to service order
 264 notifications. 3 events are managed:
 265
 266 • A new service order is created in **NBI**
 267 • A service order state changes
 268 • A service order item state changes
 269
 270 These 3 events have distinct notification allowing any system to subscribe to
 271 one, two or all notification types.
 272
 273 The implementation will be split in 2 components:
 274
 275 • A HUB resource must be managed within the NBI/serviceOrder API. This HUB
 276   resource allows system to subscribe to **NBI** notification
 277 • An Event API must be available at listener side in order to be able to
 278   receive Listener (when event occurs). **NBI** will be upgraded to use this
 279   API as client – **NBI** will shoot ``POST listener/``
 280
 281 The following diagram illustrates such notification flow:
 282
 283 .. image:: images/notification.jpg
 284    :width: 800px
 285
 286
 287 ***************
 288 Developer Guide
 289 ***************
 290
 291 Technical information about **NBI** (dependencies, configuration, running &
 292 testing) could be found here:
 293 :doc:`NBI_Developer_Guide <../architecture/NBI_Developer_Guide>`
 294
 295 API Flow illustration (with example messages) is described in this document:
 296 :download:`nbicallflow.pdf <pdf/nbicallflow.pdf>`