Add Headers and body to API Transports (#10614)

* Add Headers and body
add PUT Method

* fix check length of headers

* bad commit

* style check

* better body description

* Descr and RFC enforcement on 'PUT' and body

Only PUT can accept a statically defined body. GET will ignore it (RFC) and POST body is generated with the parameters.

* Process the variables as well for headers

* Update Api.php

* update docs

LibreNMS/Alert/Transport/Api.php

@@ -34,28 +34,38 @@ class Api extends Transport
     {
         $url = $this->config['api-url'];
         $options = $this->config['api-options'];
+        $headers = $this->config['api-headers'];
+        $body = $this->config['api-body'];
         $method = $this->config['api-method'];
         $auth = [$this->config['api-auth-username'], $this->config['api-auth-password']];
-        return $this->contactAPI($obj, $url, $options, $method, $auth);
+        return $this->contactAPI($obj, $url, $options, $method, $auth, $headers, $body);
     }
 
-    private function contactAPI($obj, $api, $options, $method, $auth)
+    private function contactAPI($obj, $api, $options, $method, $auth, $headers, $body)
     {
         $request_opts = [];
+        $request_heads = [];
         $query = [];
 
         $method = strtolower($method);
         $host = explode("?", $api, 2)[0]; //we don't use the parameter part, cause we build it out of options.
 
-        //get each line of key-values and process the variables;
+        //get each line of key-values and process the variables for Headers;
+        foreach (preg_split("/\\r\\n|\\r|\\n/", $headers, -1, PREG_SPLIT_NO_EMPTY) as $current_line) {
+            list($u_key, $u_val) = explode('=', $current_line, 2);
+            foreach ($obj as $p_key => $p_val) {
+                $u_val = str_replace("{{ $" . $p_key . ' }}', $p_val, $u_val);
+            }
+            //store the parameter in the array for HTTP headers
+            $request_heads[$u_key] = $u_val;
+        }
+        //get each line of key-values and process the variables for Options;
         foreach (preg_split("/\\r\\n|\\r|\\n/", $options, -1, PREG_SPLIT_NO_EMPTY) as $current_line) {
             list($u_key, $u_val) = explode('=', $current_line, 2);
-
             // Replace the values
             foreach ($obj as $p_key => $p_val) {
                 $u_val = str_replace("{{ $" . $p_key . ' }}', $p_val, $u_val);
             }
-            
             //store the parameter in the array for HTTP query
             $query[$u_key] = $u_val;
         }
@@ -64,9 +74,16 @@ class Api extends Transport
         if (isset($auth) && !empty($auth[0])) {
             $request_opts['auth'] = $auth;
         }
+        if (count($request_heads) > 0) {
+            $request_opts['headers'] = $request_heads;
+        }
         if ($method == "get") {
             $request_opts['query'] = $query;
             $res = $client->request('GET', $host, $request_opts);
+        } elseif ($method == "put") {
+            $request_opts['query'] = $query;
+            $request_opts['body'] = $body;
+            $res = $client->request('PUT', $host, $request_opts);
         } else { //Method POST
             $request_opts['form_params'] = $query;
             $res = $client->request('POST', $host, $request_opts);
@@ -92,11 +109,12 @@ class Api extends Transport
                 [
                     'title' => 'API Method',
                     'name' => 'api-method',
-                    'descr' => 'API Method: GET or POST',
+                    'descr' => 'API Method: GET, POST or PUT',
                     'type' => 'select',
                     'options' => [
                         'GET' => 'GET',
-                        'POST' => 'POST'
+                        'POST' => 'POST',
+                        'PUT' => 'PUT'
                     ]
                 ],
                 [
@@ -111,6 +129,18 @@ class Api extends Transport
                     'descr' => 'Enter the options (format: option=value separated by new lines)',
                     'type' => 'textarea',
                 ],
+                [
+                    'title' => 'headers',
+                    'name' => 'api-headers',
+                    'descr' => 'Enter the headers (format: option=value separated by new lines)',
+                    'type' => 'textarea',
+                ],
+                [
+                    'title' => 'body',
+                    'name' => 'api-body',
+                    'descr' => 'Enter the body (only used by PUT method, discarded otherwise)',
+                    'type' => 'textarea',
+                ],
                 [
                     'title' => 'Auth Username',
                     'name' => 'api-auth-username',
@@ -125,7 +155,7 @@ class Api extends Transport
                 ]
             ],
             'validation' => [
-                'api-method' => 'in:GET,POST',
+                'api-method' => 'in:GET,POST,PUT',
                 'api-url' => 'required|url'
             ]
         ];

doc/Alerting/Transports.md

@@ -64,11 +64,18 @@ entered as a new line.
 
 ## API
 
-The API transport allows to reach any service provider using POST or GET URLs
+The API transport allows to reach any service provider using POST, PUT or GET URLs
 (Like SMS provider, etc). It can be used in multiple ways:
 
-- The same text built from the Alert template is available in the variable `$msg`, which can then be sent as an option to the API. Be carefull that HTTP GET requests are usually limited in length.
+- The same text built from the Alert template is available in the variable
-- The API-Option fields can be directly built from the variables defined in [Template-Syntax](Templates.md#syntax) but without the 'alert->' prefix. For instance, ``` $alert->uptime ``` is available as ``` $uptime ``` in the API transport
+``` $msg ```, which can then be sent as an option to the API. Be carefull that
+HTTP GET requests are usually limited in length.
+- The API-Option fields can be directly built from the variables defined in
+[Template-Syntax](Templates.md#syntax) but without the 'alert->' prefix.
+For instance, ``` $alert->uptime ``` is available as ``` $uptime ``` in the
+API transport
+- The API-Headers allows you to add the headers that the api endpoint requires.
+- The API-body allow sending data in the format required by the ApI endpoint.
 
 A few variables commonly used :
 
@@ -112,6 +119,16 @@ the title and text of the alert to a screen in the Network Operation Center.
 | API URL       | <http://my.example.com/wall-display>
 | API Options   | title={{ $title }} <br/> msg={{ $msg }}|
 
+The example below will use the API named component of my.example.com with id 1, body as json status value and headers send token authentication and content type required.
+
+| Config | Example |
+| ------ | ------- |
+| API Method    | PUT |
+| API URL       | http://my.example.com/comonent/1
+| API Headers   | X-Token=HASH
+|               | Content-Type=application/json
+| API Body      | { "status": 2 }
+
 ## Boxcar
 
 Copy your access token from the Boxcar app or from the Boxcar.io