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

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2
   3 .. _acm-rest-apis-label:
   4
   5 REST APIs for CLAMP Automation Compositions
   6 ###########################################
   7
   8
   9 Commissioning API
  10 =================
  11
  12 This API is a CRUD API that allows **Automation Composition Type** definitions, created in a design
  13 environment, to be commissioned on the CLAMP runtime. It has endpoints that allow Automation
  14 Composition Types to be created, read, updated, and deleted.
  15
  16 The body of the *create* and *update* endpoints is a TOSCA Service/Topology template that
  17 defines the new or changed Automation Composition Type. The *update* and *delete* endpoints take a
  18 UUID reference to the Automation Composition Type. The incoming TOSCA is verified and checked for
  19 referential integrity. On *delete* requests, a check is made to ensure that no Automation
  20 Composition Instances exist for the Automation Composition Type to be deleted.
  21 An endpoint is used for *priming* or *depriming* an Automation Composition Definition, and it sends
  22 the Automation Composition Element Types to the participants.
  23 :ref:`More info here<clamp-runtime-acm>`.
  24
  25 .. csv-table::
  26    :header: "Commissioning API"
  27    :widths: 10
  28
  29    `ACM-R Commissioning Swagger <./local-swagger.html#tag/Automation-Composition-Definition>`_
  30
  31
  32 Instantiation API
  33 =================
  34
  35 The instantiation API has two functions:
  36
  37 #. Creation, Reading, Update, and Deletion of Automation Composition Instances.
  38 #. Instantiation and lifecycle management of Automation Composition Instances on participants.
  39
  40 Instantiation Automation Composition Instance CRUD
  41 --------------------------------------------------
  42
  43 This API allows for the creation, read, update, and deletion of Automation Composition
  44 Instances. The endpoints for *create* and *update* take a JSON body that describes the Automation
  45 Composition Instance and needs the UUID of the Automation Composition Type.
  46 The endpoints for *read* and *delete* take a Automation Composition Type
  47 UUID to determine which Automation Composition Type to act on, and if specified the UUID of the
  48 Automation Composition Instance.
  49 For the *delete* endpoint it needs both the UUID of the Automation Composition Type and UUID of the
  50 Automation Composition Instance, and a check is made to ensure that the Automation Composition Instance
  51 is not instantiated on participants.
  52
  53 A call to the update endpoint for a Automation Composition Instance follows the semantics described
  54 here: :ref:`Issues AC instance to change status<clamp-runtime-acm>`.
  55
  56 The endpoint to issue Automation Composition Instances to change status is used to manage the lifecycle of Automation Composition Instances. An Automation
  57 Composition Instance can be in the states described here: :ref:`2.1 Automation Composition Instance
  58 States <acm-instance-states>`. Managing the lifecycle of an Automation Composition Instance amounts
  59 to steering the Automation Composition through its states.
  60
  61 The API allows upgrades and downgrades of Automation Composition Instances to be pushed to
  62 participants following the semantics described here: :ref:`4.1 Management of Automation Composition
  63 Instance Configurations <management-acm-instance-configs>`.
  64
  65 When the API is used to update the participants on a Automation Composition Instance,
  66 the new/upgraded/downgraded definition of the
  67 Automation Composition is pushed to the participants. Note that the API asks the participants in an
  68 Automation Composition Instance to perform the update, it is the responsibility of the participants
  69 to execute the update and report the result using the protocols described here: :ref:`CLAMP
  70 Participants <clamp-acm-participants>`. The progress and result of an update can be monitored
  71 using the :ref:`Monitoring API <monitoring-api>`.
  72
  73 The API also allows a state change of an Automation Composition Instance to be ordered. The
  74 required state of the Automation Composition Instance is pushed to participants in an Automation
  75 Composition Instance using the API. Note that the API asks the participants in an Automation
  76 Composition Instance to perform the state change, it is the responsibility of the participants to
  77 execute the state change and report the result using the protocols described here: :ref:`CLAMP
  78 Participants <clamp-acm-participants>`. The progress and result of a state change can be monitored
  79 using the `Monitoring API <monitoring-api>`.
  80
  81 .. csv-table::
  82    :header: "Instantiation API"
  83    :widths: 10
  84
  85    `ACM-R Instantiation Swagger <./local-swagger.html#tag/Automation-Composition-Instance>`_
  86
  87 .. _monitoring-api:
  88
  89 Monitoring API
  90 ==============
  91
  92 The Monitoring API allows the information and status of *Participants*, *Automation Composition
  93 Instances* and their *Automation Composition Elements* to be monitored, via an hearthbeat report.
  94 The API provides filtering so that specific Participants and Automation Composition Instances
  95 can be retrieved.
  96
  97 .. csv-table::
  98    :header: "Monitoring API"
  99    :widths: 10
 100
 101    `ACM-R Monitoring Swagger <./local-swagger.html#tag/Participant-Monitoring>`_
 102
 103 End of Document