[Synthetics] Global params Public APIs (elastic#169669)

docs/api/synthetics/params/add-param.asciidoc

@@ -0,0 +1,123 @@
+[[add-parameters-api]]
+== Add Parameters API
+++++
+<titleabbrev>Add Parameters</titleabbrev>
+++++
+
+Adds one or more parameters to the synthetics app.
+
+=== {api-request-title}
+
+`POST <kibana host>:<port>/api/synthetics/params`
+
+`POST <kibana host>:<port>/s/<space_id>/api/synthetics/params`
+
+=== {api-prereq-title}
+
+You must have `all` privileges for the *Synthetics* feature in the *{observability}* section of the
+<<kibana-feature-privileges,{kib} feature privileges>>.
+
+
+[[parameters-add-request-body]]
+==== Request body
+
+The request body can contain either a single parameter object or an array of parameter objects. The parameter object schema includes the following attributes:
+
+`key`::
+(Required, string) The key of the parameter.
+
+`value`::
+(Required, string) The value associated with the parameter.
+
+`description`::
+(Optional, string) A description of the parameter.
+
+`tags`::
+(Optional, array of strings) An array of tags to categorize the parameter.
+
+`share_across_spaces`::
+(Optional, boolean) Whether the parameter should be shared across spaces.
+
+When adding a single parameter, provide a single object. When adding multiple parameters, provide an array of parameter objects.
+
+[[parameters-add-example]]
+==== Example
+
+Here are examples of POST requests to add parameters, either as a single parameter or as an array of parameters:
+
+To add a single parameter:
+
+[source,sh]
+--------------------------------------------------
+POST /api/synthetics/params
+{
+  "key": "your-key-name",
+  "value": "your-parameter-value",
+  "description": "Param to use in browser monitor",
+  "tags": ["authentication", "security"],
+  "share_across_spaces": true
+}
+--------------------------------------------------
+
+To add multiple parameters:
+
+[source,sh]
+--------------------------------------------------
+POST /api/synthetics/params
+[
+  {
+    "key": "param1",
+    "value": "value1"
+  },
+  {
+    "key": "param2",
+    "value": "value2"
+  }
+]
+--------------------------------------------------
+
+The API returns a response based on the request. If you added a single parameter, it will return a single parameter object. If you added multiple parameters, it will return an array of parameter objects.
+
+[[parameters-add-response-example]]
+==== Response Example
+
+The API response includes the created parameter(s) as JSON objects, where each parameter object has the following attributes:
+
+- `id` (string): The unique identifier of the parameter.
+- `key` (string): The key of the parameter.
+- `value` (string): The value associated with the parameter.
+- `description` (string, optional): The description of the parameter.
+- `tags` (array of strings, optional): An array of tags associated with the parameter.
+- `share_across_spaces` (boolean, optional): Indicates whether the parameter is shared across spaces.
+
+Here's an example response for a single added parameter:
+
+[source,json]
+--------------------------------------------------
+{
+  "id": "unique-parameter-id",
+  "key": "your-key-name",
+  "value": "your-param-value",
+  "description": "Param to use in browser monitor",
+  "tags": ["authentication", "security"],
+  "share_across_spaces": true
+}
+--------------------------------------------------
+
+And here's an example response for adding multiple parameters:
+
+[source,json]
+--------------------------------------------------
+[
+  {
+    "id": "param1-id",
+    "key": "param1",
+    "value": "value1"
+  },
+  {
+    "id": "param2-id",
+    "key": "param2",
+    "value": "value2"
+  }
+]
+--------------------------------------------------

docs/api/synthetics/params/delete-param.asciidoc

@@ -0,0 +1,67 @@
+[[delete-parameters-api]]
+== Delete Parameters API
+++++
+<titleabbrev>Delete Parameters</titleabbrev>
+++++
+
+Deletes one or more parameters from the Synthetics app.
+
+=== {api-request-title}
+
+`DELETE <kibana host>:<port>/api/synthetics/params`
+
+`DELETE <kibana host>:<port>/s/<space_id>/api/synthetics/params`
+
+=== {api-prereq-title}
+
+You must have `all` privileges for the *Synthetics* feature in the *{observability}* section of the
+<<kibana-feature-privileges,{kib} feature privileges>>.
+
+You must have `all` privileges for the *Synthetics* feature in the *{observability}* section of the
+<<kibana-feature-privileges,{kib} feature privileges>>.
+
+[[parameters-delete-request-body]]
+==== Request Body
+
+The request body should contain an array of parameter IDs that you want to delete.
+
+`ids`::
+(Required, array of strings) An array of parameter IDs to delete.
+
+
+Here is an example of a DELETE request to delete a list of parameters by ID:
+
+[source,sh]
+--------------------------------------------------
+DELETE /api/synthetics/params
+{
+  "ids": [
+    "param1-id",
+    "param2-id"
+  ]
+}
+--------------------------------------------------
+
+[[parameters-delete-response-example]]
+==== Response Example
+
+The API response includes information about the deleted parameters, where each entry in the response array contains the following attributes:
+
+- `id` (string): The unique identifier of the deleted parameter.
+- `deleted` (boolean): Indicates whether the parameter was successfully deleted (`true` if deleted, `false` if not).
+
+Here's an example response for deleting multiple parameters:
+
+[source,sh]
+--------------------------------------------------
+[
+  {
+    "id": "param1-id",
+    "deleted": true
+  },
+  {
+    "id": "param2-id",
+    "deleted": true
+  }
+]
+--------------------------------------------------

docs/api/synthetics/params/edit-param.asciidoc

@@ -0,0 +1,70 @@
+[[edit-parameter-by-id-api]]
+== Edit Parameter by ID API
+++++
+<titleabbrev>Edit Parameter</titleabbrev>
+++++
+
+Edits a parameter with the specified ID.
+
+=== {api-request-title}
+
+`PUT <kibana host>:<port>/api/synthetics/params`
+
+`PUT <kibana host>:<port>/s/<space_id>/api/synthetics/params`
+
+=== {api-prereq-title}
+
+You must have `all` privileges for the *Synthetics* feature in the *{observability}* section of the
+<<kibana-feature-privileges,{kib} feature privileges>>.
+
+[[parameter-edit-path-params]]
+==== Path Parameters
+
+`id`::
+(Required, string) The unique identifier of the parameter to be edited.
+
+[[parameter-edit-request-body]]
+==== Request body
+
+The request body should contain the following attributes:
+
+`key`::
+(Required, string) The key of the parameter.
+
+`value`::
+(Required, string) The updated value associated with the parameter.
+
+`description`::
+(Optional, string) The updated description of the parameter.
+
+`tags`::
+(Optional, array of strings) An array of updated tags to categorize the parameter.
+
+[[parameter-edit-example]]
+==== Example
+
+Here is an example of a PUT request to edit a parameter by its ID:
+
+[source,sh]
+--------------------------------------------------
+PUT /api/synthetics/params/param_id1
+{
+  "key": "updated_param_key",
+  "value": "updated-param-value",
+  "description": "Updated Param to be used in browser monitor",
+  "tags": ["authentication", "security", "updated"]
+}
+--------------------------------------------------
+
+The API returns the updated parameter as follows:
+
+[source,json]
+--------------------------------------------------
+{
+  "id": "param_id1",
+  "key": "updated_param_key",
+  "value": "updated-param-value",
+  "description": "Updated Param to be used in browser monitor",
+  "tags": ["authentication", "security", "updated"]
+}
+--------------------------------------------------

docs/api/synthetics/params/get-params.asciidoc

@@ -0,0 +1,128 @@
+[[get-parameters-api]]
+== Get Parameters API
+++++
+<titleabbrev>Get Parameters</titleabbrev>
+++++
+
+Retrieves parameters based on the provided criteria.
+
+=== {api-request-title}
+
+`GET <kibana host>:<port>/api/synthetics/params/{id?}`
+
+`GET <kibana host>:<port>/s/<space_id>/api/synthetics/params/{id?}`
+
+=== {api-prereq-title}
+
+You must have `read` privileges for the *Synthetics* feature in the *{observability}* section of the
+<<kibana-feature-privileges,{kib} feature privileges>>.
+
+[[parameters-get-query-params]]
+==== Query Parameters
+
+`id`::
+(Optional, string) The unique identifier of the parameter. If provided, this API will retrieve a specific parameter by its ID. If not provided, it will retrieve a list of all parameters.
+
+[[parameters-get-response-example]]
+==== Response Example
+
+The API response includes parameter(s) as JSON objects, where each parameter object has the following attributes:
+
+- `id` (string): The unique identifier of the parameter.
+- `key` (string): The key of the parameter.
+
+If the user has read-only permissions to the Synthetics app, the following additional attributes will be included:
+
+- `description` (string, optional): The description of the parameter.
+- `tags` (array of strings, optional): An array of tags associated with the parameter.
+- `namespaces` (array of strings): Namespaces associated with the parameter.
+
+If the user has write permissions, the following additional attribute will be included:
+
+- `value` (string): The value associated with the parameter.
+
+
+Here's an example request for retrieving a single parameter by its ID:
+
+[source,sh]
+--------------------------------------------------
+GET /api/synthetics/params/unique-parameter-id
+--------------------------------------------------
+
+
+Here's an example response for retrieving a single parameter by its ID:
+
+For users with read-only permissions:
+
+[source,json]
+--------------------------------------------------
+{
+  "id": "unique-parameter-id",
+  "key": "your-api-key",
+  "description": "Param to use in browser monitor",
+  "tags": ["authentication", "security"],
+  "namespaces": ["namespace1", "namespace2"]
+}
+--------------------------------------------------
+
+For users with write permissions:
+
+[source,json]
+--------------------------------------------------
+{
+  "id": "unique-parameter-id",
+  "key": "your-param-key",
+  "description": "Param to use in browser monitor",
+  "tags": ["authentication", "security"],
+  "namespaces": ["namespace1", "namespace2"],
+  "value": "your-param-value"
+}
+--------------------------------------------------
+
+And here's an example response for retrieving a list of parameters:
+
+For users with read-only permissions:
+
+[source,json]
+--------------------------------------------------
+[
+  {
+    "id": "param1-id",
+    "key": "param1",
+    "description": "Description for param1",
+    "tags": ["tag1", "tag2"],
+    "namespaces": ["namespace1"]
+  },
+  {
+    "id": "param2-id",
+    "key": "param2",
+    "description": "Description for param2",
+    "tags": ["tag3"],
+    "namespaces": ["namespace2"]
+  }
+]
+--------------------------------------------------
+
+For users with write permissions:
+
+[source,json]
+--------------------------------------------------
+[
+  {
+    "id": "param1-id",
+    "key": "param1",
+    "description": "Description for param1",
+    "tags": ["tag1", "tag2"],
+    "namespaces": ["namespace1"],
+    "value": "value1"
+  },
+  {
+    "id": "param2-id",
+    "key": "param2",
+    "description": "Description for param2",
+    "tags": ["tag3"],
+    "namespaces": ["namespace2"],
+    "value": "value2"
+  }
+]
+--------------------------------------------------