docs/clamp/acm/api-protocol/controlloop-rest-apis.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2
   3 .. _controlloop-rest-apis-label:
   4
   5 REST APIs for CLAMP Control Loops
   6 #################################
   7
   8
   9 Commissioning API
  10 =================
  11
  12 This API is a CRUD API that allows Control Loop Type definitions created in a design
  13 environment to be commissioned on the CLAMP runtime. It has endpoints that allow Control
  14 Loop Types to be created, read, updated, and deleted.
  15
  16 The body of the create and update end points is a TOSCA Service/Topology template that
  17 defines the new or changed Control Loop Type. The update and delete endpoints take a
  18 reference to the Control Loop Type. The incoming TOSCA is verified and checked for
  19 referential integrity. On delete requests, a check is made to ensure that no Control
  20 Loop Instances exist for the Control Loop Type to be deleted.
  21
  22 :download:`Download Policy Control Loop Commissioning API Swagger  <swagger/controlloop-comissioning.json>`
  23
  24 .. swaggerv2doc:: swagger/controlloop-comissioning.json
  25
  26
  27 Instantiation API
  28 =================
  29
  30 The instantiation API has two functions:
  31
  32 #. Creation, Reading, Update, and Deletion of Control Loop Instances.
  33 #. Instantiation and lifecycle management of Control Loop Instances on participants
  34
  35 The Instantiation API is used by the CLAMP GUI.
  36
  37 Instantiation Control Loop Instance CRUD
  38 ----------------------------------------
  39
  40 This sub API allows for the creation, read, update, and deletion of Control Loop Instances.
  41 The endpoints for create and update take a JSON body that describes the Control Loop Instance.
  42 The endpoints for read and delete take a Control Loop Instance ID to determine which Control
  43 Loop Instance to act on. For the delete endpoint, a check is made to ensure that the Control
  44 Loop Instance is not instantiated on participants.
  45
  46 A call to the update endpoint for a Control Loop Instance follow the semantics described here:
  47 `4.1 Management of Control Loop Instance Configurations <management-cl-instance-configs>`.
  48
  49 :download:`Download Policy Control Loop Instantiation API Swagger  <swagger/controlloop-instantiation.json>`
  50
  51 .. swaggerv2doc:: swagger/controlloop-instantiation.json
  52
  53
  54 Instantiation Control Loop Instance Lifecycle Management
  55 --------------------------------------------------------
  56
  57 This sub API is used to manage the life cycle of Control Loop Instances. A Control Loop Instance
  58 can be in the states described here: `2.1 Control Loop Instance States <controlloop-instance-states>`.
  59 Managing the life cycle of a Control Loop Instance amounts to steering the Control Loop through
  60 its states.
  61
  62 The sub API allows upgrades and downgrades of Control Loop Instances to be pushed to participants
  63 following the semantics described here: `4.1 Management of Control Loop Instance Configurations
  64 <management-cl-instance-configs>`. When the API is used to update the participants on a Control
  65 Loop Instance, the new/upgraded/downgraded definition of the Control Loop is pushed to the
  66 participants. Note that the API asks the participants in a Control Loop Instance to perform the
  67 update, it is the responsibility of the participants to execute the update and report the result
  68 using the protocols described here: `CLAMP Participants <#>`_. The progress and result of an update
  69 can be monitored using the `Monitoring API <monitoring-api>`.
  70
  71 The sub API also allows a state change of a Control Loop Instance to be ordered. The required state
  72 of the Control Loop Instance is pushed to participants in a Control Loop Instance using the API.
  73 Note that the API asks the participants in a Control Loop Instance to perform the state change, it
  74 is the responsibility of the participants to execute the state change and report the result using
  75 the protocols described here: CLAMP Participants. The progress and result of a state change can be
  76 monitored using the `Monitoring API <monitoring-api>`.
  77
  78 .. warning::
  79    The Swagger for the Instantiation Lifecycle Management API will appear here.
  80
  81 .. _monitoring-api:
  82
  83 Monitoring API
  84 ==============
  85
  86 The Monitoring API allows the state and statistics of Participants, Control Loop Instances and their Control Loop Elements to be monitored. This API is used by the CLAMP GUI. The API provides filtering so that specific Participants and Control Loop Instances can be retrieved. In addition, the quantity of statistical information to be returned can be scoped.
  87
  88 :download:`Download Policy Control Loop Monitoring API Swagger  <swagger/controlloop-monitoring.json>`
  89
  90 .. swaggerv2doc:: swagger/controlloop-monitoring.json
  91
  92 Pass Through API
  93 ================
  94
  95 This API allows information to be passed to Control Loop Elements in a control loop.
  96
  97 .. warning::
  98    The requirements on this API are still under discussion.
  99
 100 .. warning::
 101    The Swagger for the Pass Through API will appear here.
 102
 103
 104 Participant Standalone API
 105 ==========================
 106
 107 This API allows a Participant to run in standalone mode and to run standalone Control Loop Elements.
 108
 109 Kubernetes participant can also be deployed as a standalone application and provides REST end points
 110 for onboarding helm charts to its local chart storage, installing and uninstalling of helm charts to
 111 a kubernetes cluster. It also allows to configure a remote repository in kubernetes participant for
 112 installing helm charts. User can onboard a helm chart along with the overrides yaml file, the chart
 113 gets stored in to the local chart directory of kubernetes participant. The onboarded charts can be
 114 installed, uninstalled. The GET API fetches all the available helm charts from the chart storage.
 115
 116 :download:`Download Policy Control Loop Participant Standalone API Swagger  <swagger/k8sparticipant.json>`
 117
 118 .. swaggerv2doc:: swagger/k8sparticipant.json
 119
 120
 121 Participant Simulator API
 122 =========================
 123
 124 This API allows a Participant Simulator to be started and run for test purposes.
 125
 126 :download:`Download Policy Participant Simulator API Swagger  <swagger/participant-sim.json>`
 127
 128 .. swaggerv2doc:: swagger/participant-sim.json
 129
 130 End of Document