Added /testhttp Endpoint

2025-05-14 03:41:42 +02:00 · 2025-05-14 03:41:42 +02:00 · 268e14889c
parent 4ca7c8d98a
commit 268e14889c
1 changed files with 115 additions and 0 deletions
--- a/testhttp/README.md
+++ b/testhttp/README.md
@ -0,0 +1,115 @@
+# Endpoint api.zaks.web.za/testhttp
+
+Tests if http and/or https on a given IPv4 Address or Domain is working and accessible from the Internet at large.
+
+## Basic Usage
+
+By invoking the endpoint with no data, it will test the http and https connectivity to your current IP address.
+
+### Usage example:
+
+```
+curl "http://api.zaks.web.za/testhttp"
+```
+
+### Response example:
+
+```
+{
+  "http": {
+    "ipv4": "12.34.56.78",
+    "port": 80,
+    "result": "OK",
+    "message": "HTTP/1.1 301 Moved Permanently"
+  },
+  "https": {
+    "ipv4": "12.34.56.78",
+    "port": 443,
+    "result": "OK",
+    "message": "HTTP/2 200",
+    "certificate": {
+      "issuer": "C = US, O = Let's Encrypt, CN = R10",
+      "subject": "CN = domain.tld",
+      "expiry": "Aug 11 21:26:10 2025 GMT"
+    }
+  },
+  "notice": "This is a free public endpoint. Visit https://git.zaks.web.za/zaks-web/public-api-endpoints for documentation on available endpoints."
+}
+
+```
+## Working with Query Parameters
+
+You can add query parameters to the URI of the endpoint.
+
+Valid query parameters:
+
+**address={domain|ipv4}**
+- Using a domain (excluding the http:// or https://) will result in the test being carried out on supplied domain.
+- Using a public IPv4 address will result in the test being carried out on supplied public IPv4 address.
+
+> Currently IPv6 is not support as the API is hosted in South Africa and IPv6 roll out has not even begun here.
+
+**http={false|port}**
+- Setting this to false will exclude a test on http.
+- Setting this to a port (1-65535) will result in http being test on supplied port rather than the default port 80.
+
+**https={false|port}**
+- Setting this to false will exclude a test on https.
+- Setting this to a port (1-65535) will result in https being test on supplied port rather than the default port 443.
+
+### Usage example:
+
+```
+curl "http://api.zaks.web.za/testhttp?http=false&address=google.com"
+```
+
+### Response example:
+
+```
+{
+  "https": {
+    "domain": "google.com",
+    "port": 443,
+    "result": "OK",
+    "message": "HTTP/2 301",
+    "certificate": {
+      "issuer": "C = US, O = Google Trust Services, CN = WR2",
+      "subject": "CN = *.google.com",
+      "expiry": "Jul 14 08:40:41 2025 GMT"
+    }
+  },
+  "notice": "This is a free public endpoint. For more information visit https://git.zaks.web.za/zaks-web/public-api-endpoints"
+}
+```
+
+## Supplying JSON data
+
+You can supply the parameters as JSON data in the header
+
+### Usage example:
+
+```
+curl "http://api.zaks.web.za/testhttp" \
+    -X POST \
+    -H 'Content-Type: application/json' \
+    -d '{"address": "google.com", "http": false}'
+```
+
+### Response example:
+
+```
+{
+  "https": {
+    "domain": "google.com",
+    "port": 443,
+    "result": "OK",
+    "message": "HTTP/2 301",
+    "certificate": {
+      "issuer": "C = US, O = Google Trust Services, CN = WR2",
+      "subject": "CN = *.google.com",
+      "expiry": "Jul 14 08:40:41 2025 GMT"
+    }
+  },
+  "notice": "This is a free public endpoint. For more information visit https://git.zaks.web.za/zaks-web/public-api-endpoints"
+}
+```