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