Merge branch 'alexjustesen:main' into main

Author: svenvg93

.gitbook/assets/openapi.json

@@ -0,0 +1,51 @@
+{
+    "openapi": "3.0.0",
+    "info": {
+        "title": "Speedtest Tracker API",
+        "version": "1.0.0"
+    },
+    "paths": {
+        "/api/v1/results/latest": {
+            "get": {
+                "description": "Get the latest result.",
+                "operationId": "4b44d6935caeb91d3e687ab4bc176f62",
+                "responses": {
+                    "200": {
+                        "description": "OK"
+                    },
+                    "404": {
+                        "description": "No result found"
+                    }
+                }
+            }
+        },
+        "/api/v1/results": {
+            "get": {
+                "description": "List results.",
+                "operationId": "32a45ba8e8e9a81955a178ae686273ce",
+                "responses": {
+                    "200": {
+                        "description": "OK"
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity"
+                    }
+                }
+            }
+        },
+        "/api/v1/results/{id}": {
+            "get": {
+                "description": "Get result.",
+                "operationId": "bc182a4008f0ff94a6318893359f3adc",
+                "responses": {
+                    "200": {
+                        "description": "OK"
+                    },
+                    "404": {
+                        "description": "Result not found"
+                    }
+                }
+            }
+        }
+    }
+}

README.md

@@ -8,7 +8,7 @@ description: >-
 # Introduction
 
 {% hint style="info" %}
-Docs are up to date through version: `v1.0.1`
+Docs are up to date through version: `v1.1.0`
 {% endhint %}
 
 <figure><img src=".gitbook/assets/dashboard.png" alt=""><figcaption></figcaption></figure>

SUMMARY.md

@@ -52,7 +52,8 @@
 
 ## 🖥️ API
 
-* [Latest Result](api/latest-result.md)
+* [v1](api/v1.md)
+* [Latest Result (deprecated)](api/latest-result.md)
 
 ## 🤹 Contributing
 

api/latest-result.md

@@ -1,5 +1,9 @@
 # Latest Result
 
+{% hint style="warning" %}
+This endpoint is deprecated and will be removed in a future release.
+{% endhint %}
+
 ### Authentication
 
 No authentication required.

api/v1.md

@@ -0,0 +1,145 @@
+# v1
+
+### Authorization
+
+A "Bearer Token" is required to authenticate into the API, you can generate tokens for your user account on `/admin/api-tokens`.
+
+***
+
+### Get result
+
+<pre class="language-bash"><code class="lang-bash"><strong>curl localhost/api/v1/results/{id}
+</strong>   -H "Accept: application/json"
+   -H "Authorization: Bearer yourtokengoeshere"
+</code></pre>
+
+#### Parameters
+
+* `id`- record ID of the result to get
+
+#### Responses
+
+* 200: OK
+* 404: Result not found
+
+
+
+***
+
+### List result
+
+```bash
+curl localhost/api/v1/results
+   -H "Accept: application/json"
+   -H "Authorization: Bearer yourtokengoeshere
+```
+
+#### Filtering
+
+You can filter the results response by the fields: `ping`, `download`, `upload`, `healthy`, `status`, `scheduled`, `created_at` and `updated_at`.
+
+Example: filter dates in a range
+
+```bash
+curl localhost/api/v1/results?filter[created_at]=>=2024-01-01&filter[created_at]=<=2024-12-31
+   -H "Accept: application/json"
+   -H "Authorization: Bearer yourtokengoeshere"
+```
+
+Example: filter for only unhealthy results
+
+```bash
+curl localhost/api/v1/results?filter[healthy]=false
+   -H "Accept: application/json"
+   -H "Authorization: Bearer yourtokengoeshere"
+```
+
+Example: filter for "failed" and "skipped" results
+
+```bash
+curl localhost/api/v1/results?filter[status]=failed,skipped
+   -H "Accept: application/json"
+   -H "Authorization: Bearer yourtokengoeshere"
+```
+
+#### Sorting
+
+You can sort the results response by the fields: `ping`, `download`, `upload`, `created_at` or `updated_at`. Sorting is ascending by default and can be reversed by adding a hyphen (-) to the start of the property name.
+
+```bash
+curl localhost/api/v1/results?sort=-created_at
+   -H "Accept: application/json"
+   -H "Authorization: Bearer yourtokengoeshere"
+```
+
+#### Responses
+
+* 200: OK
+* 422: Unprocessable Entity (validation probably failed, see logs)
+
+
+
+***
+
+### Get latest result
+
+```bash
+curl localhost/api/v1/results/latest
+   -H "Accept: application/json"
+   -H "Authorization: Bearer yourtokengoeshere"
+```
+
+#### Responses
+
+* 200: OK
+* 404: No result found
+
+
+
+***
+
+### Data Dictionary
+
+The data structure returned mimic the `results` table but includes the addition of `download_bits`, `upload_bits`, `download_bits_human` and `upload_bits_human`.
+
+```json
+{
+  "data": {
+    "id": 1009,
+    "service": "ookla",
+    "ping": 7.448,
+    "download": 167270969,
+    "upload": 115884569,
+    "download_bits": 1338167752,
+    "upload_bits": 927076552,
+    "download_bits_human": "1.34 Gbps",
+    "upload_bits_human": "927.08 Mbps",
+    "benchmarks": null,
+    "healthy": null,
+    "status": "completed",
+    "scheduled": true,
+    "comments": null,
+    "data": {
+    },
+    "created_at": "2025-01-13 16:37:00",
+    "updated_at": "2025-01-13 16:37:17"
+  }
+}
+```
+
+
+
+***
+
+### FAQ
+
+<details>
+
+<summary>Can I create, update or delete results through the API?</summary>
+
+No, not at this time its read-only.
+
+</details>
+
+
+

getting-started/environment-variables.md

@@ -10,6 +10,18 @@ description: >-
 
 <table><thead><tr><th width="218">Name</th><th width="103" data-type="checkbox">Required</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><code>PUID</code></td><td>true</td><td>Used to set the user the container should run as.</td><td><code>1000</code></td></tr><tr><td><code>PGID</code></td><td>true</td><td>Used to set the group the container should run as.</td><td><code>1000</code></td></tr><tr><td><code>APP_NAME</code></td><td>false</td><td>Used to define the application's name in the dashboard and in notifications.<br></td><td></td></tr><tr><td><code>APP_KEY</code></td><td>true</td><td><p>Key used to encrypt and decrypt data.</p><p>You can generate a key at <a href="https://speedtest-tracker.dev">https://speedtest-tracker.dev</a>.</p></td><td></td></tr><tr><td><code>ADMIN_NAME</code></td><td>false</td><td>Name of the initial admin user.<br>Note: Only effective during initial setup.</td><td><code>Admin</code></td></tr><tr><td><code>ADMIN_EMAIL</code></td><td>false</td><td>Email of the initial admin user.<br>Note: Only effective during initial setup.</td><td><code>[email protected]</code></td></tr><tr><td><code>ADMIN_PASSWORD</code></td><td>false</td><td>Password of the initial admin user.<br>Note: Only effective during initial setup.</td><td><code>password</code></td></tr><tr><td><code>APP_URL</code></td><td>false</td><td>URL used for links in emails and notifications.</td><td><code>https://speedtest.example.com</code></td></tr><tr><td><code>ASSET_URL</code></td><td>false</td><td>URL used for assets, needed when using a reverse proxy.</td><td><code>https://speedtest.example.com</code></td></tr><tr><td><code>APP_TIMEZONE</code></td><td>false</td><td>Application timezone should be set if your database does not use UTC as its default timezone.</td><td><code>Europe/London</code></td></tr><tr><td><code>CHART_BEGIN_AT_ZERO</code></td><td>false</td><td>Begin the dashboard axis charts at zero.<br><br>- Default: <code>true</code></td><td><code>true</code> or <code>false</code></td></tr><tr><td><code>CHART_DATETIME_FORMAT</code></td><td>false</td><td>Set the formatting of timestamps in charts.<br><br>Formatting: <a href="https://www.php.net/manual/en/datetime.format.php">https://www.php.net/manual/en/datetime.format.php</a></td><td><code>j/m G:i</code><br>(18/10 20:06)</td></tr><tr><td><code>DATETIME_FORMAT</code></td><td>false</td><td>Set the formatting of timestamps in tables and notifications.<br><br>Formatting: <a href="https://www.php.net/manual/en/datetime.format.php">https://www.php.net/manual/en/datetime.format.php</a></td><td><code>j M Y, G:i:s</code><br>(18 Oct 2024, 20:06:01)</td></tr><tr><td><code>DISPLAY_TIMEZONE</code></td><td>false</td><td>Display timestamps in your local time.</td><td><code>America/New_York</code></td></tr><tr><td><code>CONTENT_WIDTH</code></td><td>false</td><td>Width of the content section of each page. Can be set to any value found in the Filament <a href="https://filamentphp.com/docs/3.x/panels/configuration#customizing-the-maximum-content-width">docs</a>.<br><br>- Default:<code>7xl</code></td><td></td></tr><tr><td><code>PUBLIC_DASHBOARD</code></td><td>false</td><td>Enables the public dashboard for guest (unauthenticated) users.<br><br>- Default:<code>false</code></td><td></td></tr><tr><td><code>DASHBOARD_POLLING</code></td><td>false</td><td>Frequency charts and stats refresh on the dashboard. Can be represented using a string in seconds or<code>false</code>to disable.<br><br>- Default:<code>60s</code></td><td></td></tr><tr><td><code>NOTIFICATION_POLLING</code></td><td>false</td><td>Frequency database notifications are polled. Can be represented using a string in seconds or<code>false</code>to disable.<br><br>- Default:<code>60s</code></td><td></td></tr><tr><td><code>RESULTS_POLLING</code></td><td>false</td><td>Frequency data refreshes in the results table. Can be represented using a string in seconds or<code>false</code>to disable.<br><br>- Default:<code>false</code></td><td></td></tr></tbody></table>
 
+
+
+***
+
 ### Speedtest
 
 <table><thead><tr><th width="221">Name</th><th data-type="checkbox">Required</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><code>SPEEDTEST_SKIP_IPS</code></td><td>false</td><td>A comma separated list of public IP addresses where tests will be skipped when present.</td><td><code>127.0.0.1</code> or <code>127.0.0.0/16</code></td></tr><tr><td><code>SPEEDTEST_SCHEDULE</code></td><td>false</td><td>Cron expression used to run speedtests on a scheduled basis. https://crontab.guru/ is a helpful tool.</td><td><code>6 */2 * * *</code><br>(<em>At minute 6 past every 2nd hour)</em></td></tr><tr><td><code>SPEEDTEST_SERVERS</code></td><td>false</td><td><p>Comma separated list of server IDs to randomly use for speedtest.</p><p>To find servers near you visit: <a href="https://c.speedtest.net/speedtest-servers-static.php">https://c.speedtest.net/speedtest-servers-static.php</a></p></td><td><code>52365</code> or <code>36998,52365</code></td></tr><tr><td><code>SPEEDTEST_BLOCKED_SERVERS</code></td><td>false</td><td>Comma separated list of server IDs that should not be used when running speedtests.</td><td></td></tr><tr><td><code>SPEEDTEST_INTERFACE</code></td><td>false</td><td>Set the network interface to use for the test. This need to be the network interface available inside the container</td><td><code>eth0</code></td></tr><tr><td><code>THRESHOLD_ENABLED</code></td><td>false</td><td>Enable the thresholds. Note: Only effective during initial setup.</td><td><code>true</code></td></tr><tr><td><code>THRESHOLD_DOWNLOAD</code></td><td>false</td><td><p>Set the Download Threshold</p><p>Note: Only effective during initial setup.</p></td><td><code>900</code></td></tr><tr><td><code>THRESHOLD_UPLOAD</code></td><td>false</td><td><p>Set the Upload Threshold</p><p>Note: Only effective during initial setup.</p></td><td><code>900</code></td></tr><tr><td><code>THRESHOLD_PING</code></td><td>false</td><td><p>Set the Ping Threshold</p><p>Note: Only effective during initial setup.</p></td><td><code>25</code></td></tr><tr><td><code>PRUNE_RESULTS_OLDER_THAN</code></td><td>false</td><td>Set the value to greater than zero to prune stored results. This value should be represented in days, e.g. <code>7</code> will purge all results over 7 days old.</td><td><code>7</code></td></tr></tbody></table>
+
+
+
+***
+
+### API
+
+<table><thead><tr><th width="221">Name</th><th data-type="checkbox">Required</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>API_RATE_LIMIT</td><td>false</td><td>Number of requests per minute to the API.<br><br>- Default: <code>60</code></td><td><code>100</code></td></tr></tbody></table>

other/data-dictionary.md

@@ -4,4 +4,4 @@
 
 #### Results
 
-<table><thead><tr><th width="181.66666666666666">Field</th><th width="188">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>primary key</td><td></td></tr><tr><td><code>service</code></td><td>string</td><td>Service user to run the speedtest.</td></tr><tr><td><code>ping</code></td><td>double</td><td>As milliseconds</td></tr><tr><td><code>download</code></td><td>unsigned big int</td><td>As bytes</td></tr><tr><td><code>upload</code></td><td>unsigned big int</td><td>As bytes</td></tr><tr><td><code>comments</code></td><td>text</td><td>User added comments.</td></tr><tr><td><code>data</code></td><td>json</td><td>The raw response from the speedtest.</td></tr><tr><td><code>status</code></td><td>string</td><td><ul><li><strong>Completed</strong> - a speedtest that ran successfully.</li><li><strong>Failed</strong> - a speedtest that failed to run successfully.</li><li><strong>Started</strong> - a speedtest that has been started but has not finished running.</li><li><strong>Skipped</strong> - a speedtest that was skipped. See message for more details.</li></ul></td></tr><tr><td><code>scheduled</code></td><td>boolean</td><td>Was the result scheduled.</td></tr><tr><td><code>created_at</code></td><td>timestamp</td><td>When the record was created.</td></tr><tr><td><code>updated_at</code></td><td>timestamp</td><td>When the record was last updated.</td></tr></tbody></table>
+<table><thead><tr><th width="181.66666666666666">Field</th><th width="188">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>primary key</td><td></td></tr><tr><td><code>service</code></td><td>string</td><td>Service user to run the speedtest.</td></tr><tr><td><code>ping</code></td><td>double</td><td>As milliseconds</td></tr><tr><td><code>download</code></td><td>unsigned big int</td><td>As bytes</td></tr><tr><td><code>upload</code></td><td>unsigned big int</td><td>As bytes</td></tr><tr><td><code>comments</code></td><td>text</td><td>User added comments.</td></tr><tr><td><code>data</code></td><td>json</td><td>The raw response from the speedtest.</td></tr><tr><td><code>benchmarks</code></td><td>json</td><td>Captures the speedtest's benchmarks at run time.</td></tr><tr><td><code>healthy</code></td><td>boolean</td><td>Indicates if the speedtest was healthy compared to the benchmark.</td></tr><tr><td><code>status</code></td><td>string</td><td><ul><li><strong>Completed</strong> - a speedtest that ran successfully.</li><li><strong>Failed</strong> - a speedtest that failed to run successfully.</li><li><strong>Started</strong> - a speedtest that has been started but has not finished running.</li><li><strong>Skipped</strong> - a speedtest that was skipped. See message for more details.</li></ul></td></tr><tr><td><code>scheduled</code></td><td>boolean</td><td>Was the result scheduled.</td></tr><tr><td><code>created_at</code></td><td>timestamp</td><td>When the record was created.</td></tr><tr><td><code>updated_at</code></td><td>timestamp</td><td>When the record was last updated.</td></tr></tbody></table>