docs/offeredapis/offeredapis.rst

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