Skip to content

EXAMPLES.md

Latest commit

 

History

History
418 lines (305 loc) · 9.32 KB

EXAMPLES.md

File metadata and controls

418 lines (305 loc) · 9.32 KB
Raw

API Bot Examples and Use Cases

This document provides examples of how to use the API Resource Availability Bot and common use cases.

🎯 Basic Usage Examples

Example 1: Check Website Availability

Input:

https://github.com

Output:

📊 Detailed Scan Report
🎯 Target: https://github.com
🕐 Time: 2026-01-24 12:00:00

🌐 Availability:
  Status: AVAILABLE
  Message: Resource is accessible
  Response Time: 0.234s

🔍 DNS Information:
  IPv4: 140.82.121.4
  IPv6: 2606:50c0:8000::153
  CNAME: None

🔒 Protocol & Security:
  Protocol: HTTPS
  SSL/TLS: ✅ Enabled
  SSL Version: TLSv1.3
  HTTP Version: HTTP/2

💰 Paywall Detection:
  Status: 🟢 None

🛡️ Security Status:
  Status: SECURE
  Overall Score: 95/100
  Vulnerabilities: 0

Example 2: Check API Endpoint

Input:

https://api.github.com/users/octocat

Output:

Target: https://api.github.com/users/octocat
Status: 🟢 Available
Response Time: 0.156s
Protocol: HTTPS
SSL/TLS: ✅ Enabled
Primary IP: 140.82.121.6
Paywall: 🟢 None
Security: ✅ Secure (98/100)

Example 3: Detect Paywall

Input:

https://www.nytimes.com/2024/01/article

Output:

Status: 🔐 Authentication Required
Paywall: 🔴 Detected (85% confidence)
Type: Metered paywall
Security: ✅ Secure

🔖 Bookmark Management

Add Multiple Bookmarks

  1. Scan first resource:
https://api.openai.com

  1. Click "🔖 Bookmark"

  2. Scan next resource:

https://httpbin.org

  1. Click "🔖 Bookmark"

  2. View all bookmarks:

/bookmarks

Check Bookmark Status

Send /bookmarks to see all saved resources with their current status:

📚 Your Bookmarks (5)

🟢 OpenAI API
🟢 HTTPBin
🔴 Example Service (Timeout)
🟢 GitHub API
🟢 Google

Click any bookmark to rescan and get updated information.

📊 Common Use Cases

Use Case 1: Monitor Multiple APIs

Scenario: You manage several APIs and want to monitor their availability.

Steps:

  1. Scan each API endpoint
  2. Bookmark them all
  3. Use /bookmarks for quick status overview
  4. Click "🔄 Refresh All" to update all statuses
  5. Check /stats to see scan history

Example APIs to monitor:

https://api.github.com
https://api.openweathermap.org
https://jsonplaceholder.typicode.com
https://dog.ceo/api/breeds/list/all

Use Case 2: Test Different Protocols

Scenario: Check if a service supports multiple protocols.

URLs to test:

http://example.com
https://example.com
ftp://ftp.example.com

Compare the results to see:

  • Which protocols are available
  • SSL/TLS versions
  • HTTP version support (HTTP/1.1, HTTP/2, HTTP/3)

Use Case 3: Security Audit

Scenario: Perform basic security check on your website.

What the bot checks:

  • ✅ SSL certificate validity
  • ✅ Security headers (HSTS, CSP, X-Frame-Options, etc.)
  • ✅ SSL/TLS version
  • ✅ Server information disclosure
  • ✅ Common vulnerabilities

Example:

https://yourwebsite.com

Review the security score and recommendations.

Use Case 4: Check Regional Accessibility

Scenario: Verify if your service is accessible from different regions.

Note: The bot scans from your server's location. For multi-region testing, deploy multiple bot instances in different regions.

What to check:

  • Status: AVAILABLE vs REGION_BLOCKED
  • Response times (latency)
  • Content differences

Use Case 5: Paywall Research

Scenario: Research which sites use paywalls and what type.

Test different sites:

https://www.wsj.com
https://www.nytimes.com
https://medium.com/@user/article

The bot detects:

  • Hard paywalls (402 Payment Required)
  • Soft paywalls (registration walls)
  • Metered paywalls (limited free articles)

Use Case 6: DNS Investigation

Scenario: Investigate DNS configuration of a domain.

What you get:

  • A records (IPv4)
  • AAAA records (IPv6)
  • CNAME (aliases)
  • NS (nameservers)
  • MX (mail servers)
  • TXT records
  • Resolution time

Example:

https://github.com

Perfect for troubleshooting DNS issues or verifying configurations.

⚙️ Advanced Features

Custom Settings

Configure the bot for your workflow:

  1. Detailed Reports (Default: ON)

    • ON: Full detailed reports with all information
    • OFF: Compact table view

  2. Auto Bookmark (Default: OFF)

    • ON: Automatically bookmark every scanned URL
    • OFF: Manual bookmarking

  3. Notifications (Default: ON)

    • ON: Get alerts for bookmark status changes
    • OFF: Quiet mode

Scan History

View past scans for any URL:

  1. Scan a URL multiple times over different periods
  2. Click "📋 Logs" button
  3. See history of all scans with timestamps and status changes

Use case: Track website uptime over time

Scan History for: https://api.example.com

1. 2026-01-24 12:00:00
   Status: AVAILABLE

2. 2026-01-24 06:00:00
   Status: TIMEOUT

3. 2026-01-23 18:00:00
   Status: AVAILABLE

Sharing Results

Share scan results with team members:

  1. Scan a URL
  2. Click "📤 Share" button
  3. Select a chat or person
  4. Bot sends the URL for them to scan

🔍 Interpreting Results

Status Codes

Status Meaning Action
🟢 AVAILABLE Resource is online and accessible None needed
🔴 UNAVAILABLE Resource is offline or unreachable Check if down for everyone or just you
🔐 AUTH_REQUIRED Authentication needed Verify credentials
🌍 REGION_BLOCKED Blocked by region Use VPN or check geo-restrictions
🚫 IP_BLOCKED Your IP is blocked Contact administrator
⏱️ TIMEOUT Request timed out Resource is slow or filtering requests
❌ ERROR Unexpected error Check URL format

Security Scores

Score Grade Meaning
90-100 A Excellent security
75-89 B Good security
50-74 C Adequate security
25-49 D Poor security
0-24 F Critical issues

Response Times

Time Rating
< 0.1s Excellent
0.1-0.5s Good
0.5-1s Average
1-3s Slow
> 3s Very slow

📈 Statistics Tracking

View your scanning statistics:

/stats

Output:

📊 Your Statistics

📚 Total Bookmarks: 12
🔍 Total Scans: 156

🎯 Most Scanned: https://api.github.com
   (23 times)

What you can learn:

  • How many resources you're monitoring
  • Your most-checked services
  • Total scanning activity

🔄 Automation Ideas

Daily Health Checks

  1. Bookmark all your critical services
  2. Each morning, use /bookmarks
  3. Click "🔄 Refresh All"
  4. Get instant status overview

Before Deployment

Before deploying changes:

  1. Scan your staging environment
  2. Verify all endpoints return 200
  3. Check security score
  4. Compare with production scan

API Documentation

Scan all API endpoints documented:

  1. Create bookmark for each endpoint
  2. Test regularly to ensure they're working
  3. Use scan history to track uptime

🎓 Tips & Tricks

Tip 1: Quick Status Check

Bookmark your critical services and use /bookmarks for instant visual status (🟢/🔴).

Tip 2: Compare Protocols

Scan both HTTP and HTTPS versions to see differences in security and performance.

Tip 3: Monitor Changes

Scan the same URL weekly and compare security scores over time.

Tip 4: Test Rate Limits

Scan repeatedly to see if API implements rate limiting.

Tip 5: DNS Troubleshooting

If a site is slow, check DNS resolution time first.

Tip 6: Security Headers

Review missing security headers and implement them on your own sites.

Tip 7: Paywall Detection

Test with different user agents (future feature) to see paywall variations.

Tip 8: Bookmark Organization

Use descriptive titles when bookmarking (future feature) to organize better.

❓ FAQ

Q: Can I scan localhost? A: Not directly. The bot runs on a server and can't access your local machine.

Q: How often can I scan? A: The bot has rate limiting (default: 10 scans per minute). Adjust in config if needed.

Q: Why do some DNS records show empty? A: Not all domains have all record types (IPv6, MX, TXT, etc.).

Q: Can I scan non-HTTP protocols? A: Currently supports HTTP, HTTPS, FTP detection. More protocols coming soon.

Q: Is my data private? A: Yes! All scans run from your bot instance. No data sent to third parties.

Q: Can I scan IP addresses? A: Yes! Send the IP directly:

192.168.1.1
8.8.8.8

Q: Why is paywall detection not 100% accurate? A: Paywall detection uses heuristics and keyword matching. Some paywalls are sophisticated and may not be detected.

Q: Can I export my bookmarks? A: Currently stored in SQLite database. Export feature coming in future update.

Need more examples? Try these URLs:

https://httpstat.us/200
https://httpstat.us/500
https://httpstat.us/timeout
https://api.ipify.org
https://dog.ceo/api/breeds/image/random

Each will demonstrate different aspects of the bot's capabilities!