docs/design.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 (C) 2021-2023 Nordix Foundation
   4
   5 .. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING
   6 .. _design:
   7
   8
   9 CPS Design
  10 ##########
  11
  12 .. toctree::
  13    :maxdepth: 1
  14
  15 Offered APIs
  16 ============
  17
  18 CPS supports the public APIs listed in the following sections.
  19
  20 CPS-Core
  21 --------
  22
  23 CPS-Core functionality.
  24
  25 :download:`CPS Rest OpenApi Specification <api/swagger/cps/openapi.yaml>`
  26
  27 CPS-NCMP
  28 --------
  29
  30 XNF data access and module information.
  31
  32 :download:`CPS NCMP RestOpenApi Specification <api/swagger/ncmp/openapi.yaml>`
  33
  34 CPS-NCMP-Inventory
  35 ------------------
  36
  37 DMI-Plugin Inventory.
  38
  39 :download:`CPS NCMP RestOpenApi Inventory Specification <api/swagger/ncmp/openapi-inventory.yaml>`
  40
  41 View Offered APIs
  42 -----------------
  43
  44 The standard for API definition in the RESTful API world is the OpenAPI Specification (OAS).
  45 The OAS 3, which is based on the original "Swagger Specification", is being widely used in API developments.
  46
  47 Specification can be accessed using following URI:
  48
  49 .. code-block:: bash
  50
  51   http://<hostname>:<port>/v3/api-docs?group=cps-docket
  52
  53 Additionally, the Swagger User Interface can be found at the following URI. The component may be changed between CPS-Core, CPS-NCMP
  54 and CPS-NCMP-Inventory using the drop down table in the top right:
  55
  56 .. code-block:: bash
  57
  58   http://<hostname>:<port>/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/
  59
  60 Consumed APIs
  61 =============
  62
  63 CPS Core uses API's from the following ONAP components
  64
  65 * DMI-Plugin: REST based interface which is used to provide integration
  66   and allow the DMI registry API's have access to the corresponding NCMP API's within CPS Core.
  67   More information on the DMI-Plugins offered APIs can be found on the :ref:`DMI-Plugin's Design Page <onap-cps-ncmp-dmi-plugin:design>`.
  68
  69 CPS Path
  70 ========
  71
  72 Several CPS APIs use the cps-path (or cpsPath in Java API) parameter.
  73 The CPS Path is described in detail in :doc:`cps-path`.
  74
  75 CPS Delta
  76 =========
  77
  78 CPS Delta feature provides the ability to find the delta/difference between two JSON configurations.
  79 The CPS Delta feature is described in detail in :doc:`cps-delta-feature`.
  80
  81 NCMP CM Handle Querying
  82 =======================
  83
  84 The CM Handle searches endpoints can be used to query for CM Handles or CM Handle IDs.
  85 This endpoint is described in detail in :doc:`ncmp-cmhandle-querying`.
  86
  87 NCMP Inventory CM Handle Querying
  88 =================================
  89
  90 The CM Handle searches ncmp inventory endpoints can be used to query for CM Handles or CM Handle IDs.
  91 This endpoint is described in detail in :doc:`ncmp-inventory-querying`.
  92
  93 Common NCMP Response Codes
  94 ==========================
  95
  96 NCMP uses common responses codes in REST responses and events. Also the DMI plugin interface uses these codes which are defined here:
  97
  98 .. toctree::
  99    :maxdepth: 1
 100
 101    cps-ncmp-message-status-codes.rst
 102
 103 Contract Testing (stubs)
 104 ========================
 105
 106 The CPS team is committed to supporting consumers of our APIs through contract testing.
 107 Obviously we test our own contracts on a continuous basis as part of the build and delivery process.
 108 CPS uses a contract-first approach. That means we write our OpenAPi contracts first and then generate the interface code from that.
 109 This means our interface implementation simply cannot deviate from the OpenApi contracts we deliver.
 110
 111 Another advantage is that we can also generate 'stubs'. Stubs are a basic implementation of the same interface for testing purposes.
 112 These stubs can be used by clients for unit testing but also for more higher level integration-like testing where the real service is replaced by a stub.
 113 This can be useful for faster feedback loops where deployment of a full stack is difficult and not strictly needed for the purpose of the tests.
 114
 115 Stubs for contract testing typically always return the same response which is sufficient for the strict definition of a contract test.
 116 However it is often useful to allow more variation in the responses so different clients or the same client can test different scenarios without having to mock the service.
 117 CPS has implemented what we call 'extended stubs' that allow clients to provide alternate responses.implementation
 118
 119 The available stubs and how to use them are described in :doc:'cps-stubs'.
 120
 121
 122