docs/clamp/controlloop/design-impl/participants/http-participant.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2
   3 .. _clamp-controlloop-http-participant:
   4
   5 HTTP Participant
   6 ################
   7
   8 .. warning:: To be completed
   9
  10 The CLAMP HTTP participant receives configuration information from the CLAMP runtime,
  11 maps the configuration information to a REST URL, and makes a REST call on the URL.
  12 Typically the HTTP Participant is used with another participant such as the
  13 :ref:`Kubernetes Participant <clamp-controlloop-k8s-participant>`, which brings up
  14 the microservice that runs a REST server. Once the microservice is up, the HTTP
  15 participant can be used to configure the microservice over its REST interface.Of course,
  16 the HTTP participant works towards any REST service, it is not restricted to REST
  17 services started by participants.
  18
  19 .. image:: ../../images/participants/http-participant.png
  20
  21 The HTTP participant runs a Control Loop Element to handle the REST dialogues for a
  22 particular application domain. The REST dialogues are whatever REST calls that are
  23 required to implement the functionality for the application domain.
  24
  25 The HTTP participant allows the REST dialogues for a Control Loop to be managed. A
  26 particular Control Loop may require many *things* to be configured and managed and this
  27 may require many REST dialogues to achieve.
  28
  29 A *Configuration Entity* describes a concept that is managed by the HTTP participant. A
  30 Configuration Entity can be created, Read, Updated, and Deleted (CRUD). The user defines
  31 the Configuration Entities that it wants its HTTP Control Loop Element to manage and
  32 provides a sequence of parameterized REST commands to Create, Read, Update, and Delete
  33 each Configuration Entity.
  34
  35 When a control loop is initialized, the HTTP participant starts a HTTP Control Loop
  36 element for the control loop. It reads the configuration information sent from the
  37 Control Loop Runtime runs a HTTP client to talk to the REST endpoint that is receiving
  38 the REST requests. A HTTP participant can simultaneously manage HTTP Control Loop
  39 Elements towards multiple REST endpoints, as shown in the diagram above where the HTTP
  40 participant is running two HTTP Control Loop Elements, one for Control Loop A and one for
  41 Control Loop B.
  42
  43 Configuring a Control Loop Element on the HTTP participant for a Control Loop
  44 -----------------------------------------------------------------------------
  45
  46 The user configures the following properties in the CLAMP GUI for the HTTP participant:
  47
  48 .. list-table::
  49    :widths: 15 10 50
  50    :header-rows: 1
  51
  52    * - Property
  53      - Type
  54      - Description
  55    * - baseUrl
  56      - URL
  57      - A well formed URL pointing at the REST server that is processing the REST requests
  58    * - httpHeaders
  59      - map
  60      - A map of *<String, String>* defining the HTTP headers to send on all REST calls
  61    * - configurationEntitiies
  62      - map
  63      - A map of *<String, ConfigurationEntity>* describing the names and definitions of
  64        configuration entities that are managed by this HTTP Control Loop Element
  65
  66 The *ConfigurationEntity* type is described in the following table:
  67
  68 .. list-table::
  69    :widths: 15 10 50
  70    :header-rows: 1
  71
  72    * - Field
  73      - Type
  74      - Description
  75    * - ID
  76      - ToscaConceptIdentifier
  77      - The name and version of the Configuration Entity
  78    * - restSequence
  79      - List<RestRequest>
  80      - A list of REST requests to give manage the Configuration Entity
  81
  82 The *RestRequest* type is described in the following table:
  83
  84 .. list-table::
  85    :widths: 15 10 50
  86    :header-rows: 1
  87
  88    * - Field
  89      - Type
  90      - Description
  91    * - httpMethod
  92      - HttpMethod
  93      - An enum for the HTTP method {GET, PUT, POST, DELETE}
  94    * - path
  95      - String
  96      - The path of the REST endopint relative to the baseUrl
  97    * - body
  98      - String
  99      - The body of the request for POST and PUT methods
 100    * - expectedResponse
 101      - HttpStatus
 102      - The expected HTTP response code fo the REST request
 103