[synthetics] Document the request parameter (#2071)

* initial approach

* move from params/secrets to write a test

* remove detailed examples

* add info on how synthetics request is different than playwright request

* final clean up

Author: colleenmcginnis

docs/en/observability/synthetics-create-test.asciidoc

@@ -78,7 +78,7 @@ The callback provides access to fresh Playwright `page`, `params`, `browser`, an
 
 [source,js]
 ----
-journey('Journey name', ({ page, browser, context, params }) => {
+journey('Journey name', ({ page, browser, context, params, request }) => {
   // Add steps here
 });
 ----
@@ -94,6 +94,9 @@ journey('Journey name', ({ page, browser, context, params }) => {
                 For example, if you want to use a different homepage depending on the `env`
                 (`localhost` for `dev` and a URL for `prod`). See <<synthetics-params-secrets>>
                 for more information.
+`request`::     A request object that can be used to make API requests independently of the browser
+                interactions. For example, to get authentication credentials or tokens in service of a
+                browser-based test. See <<synthetics-request-param>> for more information.
 
 
 [discrete]
@@ -107,7 +110,7 @@ A basic two-step journey would look like this:
 
 [source,js]
 ----
-journey('Journey name', ({ page, browser, client, params }) => {
+journey('Journey name', ({ page, browser, client, params, request }) => {
     step('Step 1 name', () => {
       // Do something here
     });
@@ -176,6 +179,37 @@ For more details on getting started with the Synthetics Recorder, see <<syntheti
 
 image::images/synthetics-create-test-script-recorder.png[Elastic Synthetics Recorder after recording a journey and clicking Export]
 
+[discrete]
+[[synthetics-request-param]]
+== Make API requests
+
+You can use the `request` parameter to make API requests independently of browser interactions.
+For example, you could retrieve a token from an HTTP endpoint and use it in a subsequent webpage request.
+
+[source,js]
+----
+step('make an API request', async () => {
+  const response = await request.get(params.url);
+  // Do something with the response
+})
+----
+
+The Elastic Synthetics `request` parameter is similar to https://playwright.dev/docs/api/class-apirequestcontext[other request objects that are exposed by Playwright]
+with a few key differences:
+
+* The Elastic Synthetics `request` parameter comes built into the library so it doesn't
+have to be imported separately, which reduces the lines of code needed and allows you to
+make API requests in inline journeys.
+* The top level `request` object exposed by Elastic Synthetics has its own isolated cookie storage
+unlike Playwright's `context.request` and `page.request`, which share cookie storage
+with the corresponding https://playwright.dev/docs/api/class-browsercontext[`BrowserContext`].
+* If you want to control the creation of the `request` object, you can do so by passing options
+via <<elastic-synthetics-command, `--playwright-options`>> or in the
+<<synthetics-configuration, `synthetics.config.ts` file>>.
+
+NOTE: The `request` parameter is not intended to be used for writing pure API tests. Instead, it is a way to support
+writing plain HTTP requests in service of a browser-based test.
+
 [discrete]
 [[before-after]]
 == Set up and remove a global state

docs/en/observability/synthetics-params-secrets.asciidoc

@@ -53,7 +53,7 @@ These options are discussed in detail in the sections below.
 [discrete]
 [[synthetics-dynamic-configs]]
 // lint ignore params
-== Using a config file to set params
+== Use a config file to set params
 
 Use a `synthetics.config.js` or `synthetics.config.ts` file to define variables your tests always need to be defined. 
 This file should be placed in the root of your synthetics project. 
@@ -79,7 +79,7 @@ Note that we use the `env` variable in the above example, which corresponds to t
 [discrete]
 [[synthetics-cli-params]]
 // lint ignore params
-== Using CLI arguments to set params
+== Use CLI arguments to set params
 
 To set parameters when running `elastic-synthetics` on the command line, use the `--params` or `-p` flag to the `elastic-synthetics` program. The provided map is merged over any existing variables defined in the `synthetics.config.{js,ts}` file.
 
@@ -88,7 +88,7 @@ To override the `url` parameter, you would run: `elastic-synthetics . --params '
 [discrete]
 [[synthetics-hb-params]]
 // lint ignore params
-== Using {heartbeat} options to set params
+== Use {heartbeat} options to set params
 
 When running via {heartbeat} use the `params` option to set additional parameters, passed through the `--params` flag
 mentioned above and have their values merged over any default values. In the example below we run the `todos` app, overriding the `url`