chore: cleanup API domain docs (#828)

docs/reference/domains/api-domain.md

@@ -2,8 +2,11 @@
 
 The API Domain allows for collection of data (via HTTP Get or Post Requests) generically from API endpoints.
 
+>[!Important]
+>This domain supports both read and write operations (Get and Post operations), so use with care. If you configure validations with API calls that mutate resources, add the `executable` flag to the request so that Lula will ask for verification before making the API call. 
+
 ## Specification
-The API domain Specification accepts a list of `Requests` and an `Options` block. `Options` can be configured at the top-level and will apply to all requests except those which have embedded `Options`. `Request`-level options will *override* top-level `Options`.
+The API domain Specification (`api-spec`) accepts a list of `requests` and an `options` block. `options` can be configured at the top-level and will apply to all requests except those which have embedded `options`. `request`-level `options` will *override* top-level `options`.
 
 
 ```yaml
@@ -12,7 +15,7 @@ domain:
   api-spec:
     # options (optional): Options specified at this level will apply to all requests except those with an embedded options block.
     options:
-      # timeout (optional): configures the request timeout. The default timeout is 30 seconds (30s). The timeout string is a number followed by a unit suffix (ms, s, m, h, d), such as 30s or 1m.
+      # timeout (optional, default 30s): configures the request timeout. The default timeout is 30 seconds (30s). The timeout string is a number followed by a unit suffix (ms, s, m, h, d), such as 30s or 1m.
       timeout: 30s
       # proxy (optional): Specifies a proxy server for all requests.
       proxy: "https://my.proxy"
@@ -26,23 +29,23 @@ domain:
       - name: "healthcheck" 
         # url (required): The URL for the request. The API domain supports any rfc3986-formatted URI. Lula also supports URL parameters as a separate argument.
         url: "https://example.com/health/ready"
-        # method (optional): The HTTP Method to use for the API call. "get" and "post" are supported. Default is "get".
+        # method (optional, default get): The HTTP Method to use for the API call. "get" and "post" are supported. Default is "get".
         method: "get"
         # parameters (optional): parameters to append to the URL. Lula also supports full URIs in the URL.
         parameters: 
           key: "value"
         # Body (optional): a json-compatible string to pass into the request as the request body.
         body: |
 stringjsondata
-        # executable (optional): Lula will request user verification before performing API actions if *any* API request is flagged "executable".
+        # executable (optional, default false): Lula will request user verification before performing API actions if *any* API request is flagged "executable".
         executable: true
         # options (optional): Request-level options have the same specification as the api-spec-level options at the top. These options apply only to this request.
         options:
-          # timeout (optional): configures the request timeout. The default timeout is 30 seconds (30s). The timeout string is a number followed by a unit suffix (ms, s, m, h, d), such as 30s or 1m.
+          # timeout (optional, default 30s): configures the request timeout. The default timeout is 30 seconds (30s). The timeout string is a number followed by a unit suffix (ms, s, m, h, d), such as 30s or 1m.
           timeout: 30s
-          # proxy (optional): Specifies a proxy server for all requests.
+          # proxy (optional): Specifies a proxy server for this request.
           proxy: "https://my.proxy"
-          # headers (optional):  a map of key value pairs to send with all requests.
+          # headers (optional): a map of key value pairs to send with this request.
           headers: 
             key: "value"
             my-customer-header: "my-custom-value"
@@ -52,7 +55,7 @@ stringjsondata
 
 ## API Domain Resources
 
-The API response body is serialized into a json object with the Request's `Name` as the top-level key. The API status code is included in the output domain resources under `status`. `raw` contains the entire API repsonse in an unmarshalled (`json.RawMessage`) format.
+The API response body is serialized into a json object with the `request` `name` as the top-level key. The API status code is included in the output domain resources under `status`. `raw` contains the entire API repsonse in an unmarshalled (`json.RawMessage`) format.
 
 Example output:
 
@@ -78,4 +81,19 @@ provider:
       validate {
         input.healthcheck.response.healthy == true
       }
+```
+
+You can define a variable to simplify referencing the response: 
+```
+provider: 
+  type: opa
+  opa-spec:
+    rego: |
+      package validate
+
+      resp := input.healthcheck.response
+
+      validate {
+        resp == true
+      }
 ```