feat: add API and Website monitor documentation with dynamic URL placeholders

2026-04-06 00:32:12 +02:00 · 2026-02-09 14:11:02 +00:00
parent fbfa7747e0
commit c4d978cc3b
7 changed files with 300 additions and 18 deletions
--- a/Common/UI/Components/Markdown.tsx/MarkdownEditor.tsx
+++ b/Common/UI/Components/Markdown.tsx/MarkdownEditor.tsx
@@ -1,5 +1,6 @@
 import Icon from "../Icon/Icon";
 import IconProp from "../../../Types/Icon/IconProp";
+import TinyFormDocumentation from "../TinyFormDocumentation/TinyFormDocumentation";
 import React, {
  FunctionComponent,
  ReactElement,
@@ -649,23 +650,20 @@ const MarkdownEditor: FunctionComponent<ComponentProps> = (
      )}

      {/* Help Text */}
-      <div className="mt-2 text-xs text-gray-500">
-        <details className="cursor-pointer">
-          <summary className="hover:text-gray-700">Markdown help</summary>
-          <div className="mt-2 space-y-1">
-            <div>
-              <strong>**bold**</strong> or <em>*italic*</em>
-            </div>
-            <div>
-              <code className="bg-gray-100 px-1 rounded">`code`</code> or
-              ```code block```
-            </div>
-            <div># Heading 1, ## Heading 2, ### Heading 3</div>
-            <div>- Bullet list or 1. Numbered list</div>
-            <div>[Link text](url) or &gt; Quote</div>
+      <TinyFormDocumentation title="Markdown help">
+        <>
+          <div>
+            <strong>**bold**</strong> or <em>*italic*</em>
          </div>
-        </details>
-      </div>
+          <div>
+            <code className="bg-gray-100 px-1 rounded">`code`</code> or
+            ```code block```
+          </div>
+          <div># Heading 1, ## Heading 2, ### Heading 3</div>
+          <div>- Bullet list or 1. Numbered list</div>
+          <div>[Link text](url) or &gt; Quote</div>
+        </>
+      </TinyFormDocumentation>
    </div>
  );
 };
--- a/Common/UI/Components/TinyFormDocumentation/TinyFormDocumentation.tsx
+++ b/Common/UI/Components/TinyFormDocumentation/TinyFormDocumentation.tsx
@@ -0,0 +1,21 @@
+import React, { FunctionComponent, ReactElement } from "react";
+
+export interface ComponentProps {
+  title: string;
+  children: ReactElement;
+}
+
+const TinyFormDocumentation: FunctionComponent<ComponentProps> = (
+  props: ComponentProps,
+): ReactElement => {
+  return (
+    <div className="mt-2 text-xs text-gray-500">
+      <details className="cursor-pointer">
+        <summary className="hover:text-gray-700">{props.title}</summary>
+        <div className="mt-2 space-y-1">{props.children}</div>
+      </details>
+    </div>
+  );
+};
+
+export default TinyFormDocumentation;
--- a/Dashboard/src/Components/Form/Monitor/MonitorStep.tsx
+++ b/Dashboard/src/Components/Form/Monitor/MonitorStep.tsx
@@ -66,6 +66,7 @@ import MonitorStepMetricMonitor, {
  MonitorStepMetricMonitorUtil,
 } from "Common/Types/Monitor/MonitorStepMetricMonitor";
 import Link from "Common/UI/Components/Link/Link";
+import TinyFormDocumentation from "Common/UI/Components/TinyFormDocumentation/TinyFormDocumentation";
 import ExceptionMonitorStepForm from "./ExceptionMonitor/ExceptionMonitorStepForm";
 import MonitorStepExceptionMonitor, {
  MonitorStepExceptionMonitorUtil,
@@ -437,6 +438,47 @@ return {
              />
            </div>

+            {(props.monitorType === MonitorType.API ||
+              props.monitorType === MonitorType.Website) && (
+              <TinyFormDocumentation title="URL placeholder help">
+                <>
+                  <div>
+                    <code className="bg-gray-100 px-1 rounded">
+                      {"{{timestamp}}"}
+                    </code>{" "}
+                    — replaced with current Unix timestamp
+                  </div>
+                  <div>
+                    <code className="bg-gray-100 px-1 rounded">
+                      {"{{random}}"}
+                    </code>{" "}
+                    — replaced with a random unique string
+                  </div>
+                  <div>
+                    Example:{" "}
+                    <code className="bg-gray-100 px-1 rounded">
+                      {"https://example.com?cb={{timestamp}}"}
+                    </code>
+                  </div>
+                  <div>
+                    Useful for busting CDN or proxy caches on each check.{" "}
+                    <Link
+                      className="underline"
+                      openInNewTab={true}
+                      to={URL.fromString(
+                        DOCS_URL.toString() +
+                          (props.monitorType === MonitorType.API
+                            ? "/monitor/api-monitor"
+                            : "/monitor/website-monitor"),
+                      )}
+                    >
+                      Learn more.
+                    </Link>
+                  </div>
+                </>
+              </TinyFormDocumentation>
+            )}
+
            {props.monitorType === MonitorType.Port && (
              <div>
                <FieldLabelElement
--- a/Docs/Content/monitor/api-monitor.md
+++ b/Docs/Content/monitor/api-monitor.md
@@ -0,0 +1,104 @@
+# API Monitor
+
+API monitoring allows you to monitor the availability, performance, and correctness of your HTTP/REST APIs. OneUptime periodically sends HTTP requests to your API endpoints and evaluates the responses based on your configured criteria.
+
+## Overview
+
+API monitors make HTTP requests to your endpoints and check the responses. This enables you to:
+
+- Monitor API uptime and availability
+- Track response times and performance
+- Verify HTTP status codes and response bodies
+- Validate response headers
+- Test different HTTP methods (GET, POST, PUT, DELETE, etc.)
+- Send custom request headers and bodies
+
+## Creating an API Monitor
+
+1. Go to **Monitors** in the OneUptime Dashboard
+2. Click **Create Monitor**
+3. Select **API** as the monitor type
+4. Enter the API URL and configure the request settings
+5. Configure monitoring criteria as needed
+
+## Configuration Options
+
+### API URL
+
+Enter the full URL of the API endpoint you want to monitor (e.g., `https://api.example.com/v1/health`).
+
+### Dynamic URL Placeholders
+
+When monitoring APIs behind CDNs or caching proxies, the monitor may receive a cached response instead of hitting the origin server. To bust the cache on each check, you can use dynamic URL placeholders that get replaced with a unique value on every monitoring request.
+
+#### Supported Placeholders
+
+| Placeholder | Description | Example Value |
+|-------------|-------------|---------------|
+| `{{timestamp}}` | Replaced with the current Unix timestamp (seconds) | `1719500000` |
+| `{{random}}` | Replaced with a random unique string | `a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5` |
+
+#### Example
+
+Configure your monitor URL with a placeholder:
+
+```
+https://api.example.com/health?cb={{timestamp}}
+```
+
+On each monitoring check, the URL becomes:
+
+```
+https://api.example.com/health?cb=1719500000
+https://api.example.com/health?cb=1719500005
+...
+```
+
+You can also use `{{random}}` for a unique string on every request:
+
+```
+https://api.example.com/health?nocache={{random}}
+```
+
+Placeholders can appear anywhere in the URL, including the path:
+
+```
+https://api.example.com/{{timestamp}}/status
+```
+
+### API Request Type
+
+Select the HTTP method for the request:
+
+- **GET** (default)
+- **POST**
+- **PUT**
+- **DELETE**
+- **PATCH**
+- **HEAD**
+
+### Advanced Options
+
+#### Request Headers
+
+Add custom HTTP headers to the request. This is useful for authentication tokens, content type specifications, and other API-specific headers.
+
+You can use [Monitor Secrets](/docs/monitor/monitor-secrets) in header values to securely store sensitive data like API keys.
+
+#### Request Body (JSON)
+
+For POST, PUT, and PATCH requests, you can specify a JSON request body. You can use [Monitor Secrets](/docs/monitor/monitor-secrets) in the request body as well.
+
+#### Do Not Follow Redirects
+
+By default, OneUptime follows HTTP redirects (301, 302, etc.). Enable this option if you want to monitor the redirect response itself rather than the final destination.
+
+## Monitoring Criteria
+
+You can configure criteria to determine when your API is considered online, degraded, or offline based on:
+
+- **Response Status Code** - Check if the HTTP status code matches expected values (e.g., 200, 201)
+- **Response Time** - Monitor if response time exceeds a threshold
+- **Response Body** - Check if the response body contains or matches specific content
+- **Response Headers** - Verify specific response headers are present or match expected values
+- **JavaScript Expression** - Write custom expressions to evaluate the response. See [JavaScript Expressions](/docs/monitor/javascript-expression) for details.
--- a/Docs/Content/monitor/website-monitor.md
+++ b/Docs/Content/monitor/website-monitor.md
@@ -0,0 +1,81 @@
+# Website Monitor
+
+Website monitoring allows you to monitor the availability, performance, and response of any website or web page. OneUptime periodically sends HTTP requests to your website URL and checks whether it responds correctly.
+
+## Overview
+
+Website monitors check your web pages by making HTTP requests and evaluating the responses. This enables you to:
+
+- Monitor website uptime and availability
+- Track response times and performance
+- Verify HTTP status codes
+- Check response headers
+- Detect downtime before your users do
+
+## Creating a Website Monitor
+
+1. Go to **Monitors** in the OneUptime Dashboard
+2. Click **Create Monitor**
+3. Select **Website** as the monitor type
+4. Enter the website URL you want to monitor
+5. Configure monitoring criteria as needed
+
+## Configuration Options
+
+### Website URL
+
+Enter the full URL of the website you want to monitor, including the protocol (e.g., `https://example.com`).
+
+### Dynamic URL Placeholders
+
+When monitoring URLs behind CDNs or caching proxies, the monitor may receive a cached response instead of hitting the origin server. To bust the cache on each check, you can use dynamic URL placeholders that get replaced with a unique value on every monitoring request.
+
+#### Supported Placeholders
+
+| Placeholder | Description | Example Value |
+|-------------|-------------|---------------|
+| `{{timestamp}}` | Replaced with the current Unix timestamp (seconds) | `1719500000` |
+| `{{random}}` | Replaced with a random unique string | `a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5` |
+
+#### Example
+
+Configure your monitor URL with a placeholder:
+
+```
+https://example.com/health?cb={{timestamp}}
+```
+
+On each monitoring check, the URL becomes:
+
+```
+https://example.com/health?cb=1719500000
+https://example.com/health?cb=1719500005
+...
+```
+
+You can also use `{{random}}` for a unique string on every request:
+
+```
+https://example.com/health?nocache={{random}}
+```
+
+Placeholders can appear anywhere in the URL, including the path:
+
+```
+https://example.com/{{timestamp}}/status
+```
+
+### Advanced Options
+
+#### Do Not Follow Redirects
+
+By default, OneUptime follows HTTP redirects (301, 302, etc.). Enable this option if you want to monitor the redirect response itself rather than the final destination.
+
+## Monitoring Criteria
+
+You can configure criteria to determine when your website is considered online, degraded, or offline based on:
+
+- **Response Status Code** - Check if the HTTP status code matches expected values (e.g., 200, 301)
+- **Response Time** - Monitor if response time exceeds a threshold
+- **Response Body** - Check if the response body contains or matches specific content
+- **Response Headers** - Verify specific response headers are present or match expected values
--- a/Docs/Utils/Nav.ts
+++ b/Docs/Utils/Nav.ts
@@ -133,6 +133,14 @@ const DocsNav: NavGroup[] = [
  {
    title: "Monitor",
    links: [
+      {
+        title: "Website Monitor",
+        url: "/docs/monitor/website-monitor",
+      },
+      {
+        title: "API Monitor",
+        url: "/docs/monitor/api-monitor",
+      },
      {
        title: "Custom Code Monitor",
        url: "/docs/monitor/custom-code-monitor",
--- a/Probe/Utils/Monitors/Monitor.ts
+++ b/Probe/Utils/Monitors/Monitor.ts
@@ -38,6 +38,26 @@ import MonitorTest from "Common/Models/DatabaseModels/MonitorTest";
 import ProxyConfig from "../ProxyConfig";

 export default class MonitorUtil {
+  // Replace dynamic URL placeholders like {{timestamp}} and {{random}} with actual values.
+  private static resolveUrlPlaceholders(url: URL): URL {
+    let urlString: string = url.toString();
+
+    if (
+      !urlString.includes("{{timestamp}}") &&
+      !urlString.includes("{{random}}")
+    ) {
+      return url;
+    }
+
+    const timestamp: string = Math.floor(Date.now() / 1000).toString();
+    const random: string = ObjectID.generate().toString().replace(/-/g, "");
+
+    urlString = urlString.replace(/\{\{timestamp\}\}/g, timestamp);
+    urlString = urlString.replace(/\{\{random\}\}/g, random);
+
+    return URL.fromString(urlString);
+  }
+
  public static async probeMonitorTest(
    monitorTest: MonitorTest,
  ): Promise<Array<ProbeMonitorResponse | null>> {
@@ -378,8 +398,12 @@ export default class MonitorUtil {

      result.monitorDestination = monitorStep.data.monitorDestination;

-      const response: ProbeWebsiteResponse | null = await WebsiteMonitor.ping(
+      const websiteUrl: URL = MonitorUtil.resolveUrlPlaceholders(
        monitorStep.data?.monitorDestination as URL,
+      );
+
+      const response: ProbeWebsiteResponse | null = await WebsiteMonitor.ping(
+        websiteUrl,
        {
          isHeadRequest: MonitorUtil.isHeadRequest(monitorStep),
          monitorId: monitorId,
@@ -410,6 +434,10 @@ export default class MonitorUtil {

      result.monitorDestination = monitorStep.data.monitorDestination;

+      const apiUrl: URL = MonitorUtil.resolveUrlPlaceholders(
+        monitorStep.data?.monitorDestination as URL,
+      );
+
      let requestBody: JSONObject | undefined = undefined;
      if (
        monitorStep.data?.requestBody &&
@@ -421,7 +449,7 @@ export default class MonitorUtil {
      }

      const response: APIResponse | null = await ApiMonitor.ping(
-        monitorStep.data?.monitorDestination as URL,
+        apiUrl,
        {
          requestHeaders: monitorStep.data?.requestHeaders || {},
          requestBody: requestBody || undefined,