Troubleshooting APIs (DevOps) – CISCONET Training Solutions

API Troubleshooter is a lightweight diagnostic tool for software developers and DevOps. The tool automates troubleshooting tasks for API endpoints and generates a summary HTML report shareable via email. By running a suite of automated tests, it streamlines root cause analysis and also enables troubleshooting collaboration across IT teams.

DNS and network connectivity problems
SSL/TLS certificate expiry check
Authentication errors (tokens, keys, basic)
HTTP response header analysis
Cross Origin Resource Sharing (CORS)
Firewall filtering of ports and server errors

Whether your deploying a new application or investigating an incident, this tool quickly provides a summary report to accelerate the troubleshooting process. When an application goes down or performance is slow, where do you even start? Is it DNS? network latency? misconfigured server? SSL certificate? For software developers finding the root cause can be like searching for a needle in a haystack, especially when time is crucial. Download is available with troubleshooting web applications and APIs course.

System Requirements

1. Native Linux or Windows WSL
2. sudo privileges
3. Install traceroute, curl, ping
– sudo apt install traceroute
– sudo apt install curl

4. Download API Troubleshooter

Linux Install

1. Copy apidiags.tar.gz from downloads directory to /home/username directory.

2. Extract the binary and README.txt to local working directory.

tar -xzvf apidiags.tar.gz

3. Run application from the extracted directory or create a desktop shortcut.

./apidiags

Windows WSL Install

This option is recommended if you do not have native Linux desktop. ChatGPT can help troubleshoot your install based on error messages.

1. Run Windows PowerShell as administrator with right-click menu and type this command to install Windows Subsystem for Linux (WSL).

wsl --install

2. Copy apidiags.tar.gz from downloads directory to \Ubuntu\home\username\ and extract.

3. Extract the binary and README.txt to local working directory.

tar -xzvf apidiags.tar.gz

4. Run application from the extracted directory or create a desktop shortcut.

./apidiags

API Troubleshooting Report

Endpoint: https://api.github.com
Timestamp: 2025-06-07 18:17:40

DNS Resolution
✅

✅ DNS Resolution successful: Resolved IP addresses: 140.82.114.5

Connectivity Test
✅
```
✅ API connectivity test successful.
```

Traceroute Test
✅

✅ Traceroute successful:
traceroute to api.github.com (140.82.114.5), 30 hops max, 60 byte packets
 1  172.27.32.1  1.135 ms  1.117 ms  1.114 ms
 2  192.168.1.254  18.233 ms  18.231 ms  18.228 ms
 3  10.27.146.1  21.265 ms  21.263 ms  21.260 ms
 4  * * *
 5  * * *
 6  * * *
 7  154.11.15.97  19.416 ms  19.490 ms  19.463 ms
 8  208.184.12.166  19.458 ms  16.660 ms  16.638 ms
 9  64.125.31.168  89.345 ms  89.343 ms  88.436 ms
10  64.125.29.46  88.409 ms  88.406 ms  88.404 ms
11  * * *
12  * * *
13  * * *
14  * * *
15  * * *
16  64.125.24.99  90.848 ms  87.891 ms  76.190 ms
17  208.185.107.89  88.980 ms  88.886 ms  102.282 ms
18  * * *
19  * * *
20  * * *
21  140.82.114.5  90.066 ms  90.062 ms  90.059 ms

Port 443 Check
✅
```
✅ Port 443 is OPEN on api.github.com.
```

SSL Certificate Validation
✅

✅ SSL Certificate Information for api.github.com:
- Valid From: 2025-02-05 00:00:00
- Valid Until: 2026-02-05 23:59:59
- Expires in 243 days.
- TLS Version: TLSv1.3

HTTP Status Code
✅
```
✅ HTTP Status Code: 200 OK
```

HTTP Headers
✅

✅ HTTP Headers retrieved:
HTTP/2 200 
date: Sun, 08 Jun 2025 01:17:47 GMT
cache-control: public, max-age=60, s-maxage=60
vary: Accept,Accept-Encoding, Accept, X-Requested-With
x-github-api-version-selected: 2022-11-28
access-control-expose-headers: ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset
access-control-allow-origin: *
strict-transport-security: max-age=31536000; includeSubdomains; preload
x-frame-options: deny
x-content-type-options: nosniff
x-xss-protection: 0
referrer-policy: origin-when-cross-origin, strict-origin-when-cross-origin
content-security-policy: default-src 'none'
server: github.com
content-type: application/json; charset=utf-8
x-github-media-type: github.v3; format=json
etag: W/"4f825cc84e1c733059d46e76e6df9db557ae5254f9625dfe8e1b09499c449438"
accept-ranges: bytes
x-ratelimit-limit: 60
x-ratelimit-remaining: 56
x-ratelimit-reset: 1749349013
x-ratelimit-resource: core
x-ratelimit-used: 4
content-length: 2396
x-github-request-id: D93E:2345CA:20331F8:414FD15:6844E4C3

CORS Header Check
⚠️

Relevant CORS headers:
access-control-allow-origin: *
⚠️ Wildcard origin (*) means credentials won't be accepted.

Latency
✅
```
✅ Latency: 0.280 seconds
```

Authentication Test
❌

❌ Authentication failed: Unauthorized (HTTP 401).

Response snippet:
{
  "message": "Bad credentials",
  "documentation_url": "https://docs.github.com/rest",
  "status": "401"
}

API Diagnostic Tests

Security Check

This diagnostic test confirms user has sudo privileges for running traceroute command. Linux traceroute need elevated permissions to retrieve low-level system and network data.

DNS Resolution

This diagnostic test prompts user for API domain name (e.g., https://api.github.com) and attempt to resolve it to an IP address. DNS query is sent based on the provided domain name. The command output includes IP address of DNS server used to resolve hostname and one or more DNS A records. This could be a mix of IPv4 and/or IPv6 addresses. Select the first authoritative or non-authoritative answer (IP address) to use for ping test.

If successful, the test confirms registered domain name and DNS server is reachable. The test also confirms there is an A record configured on the DNS server. This does not necessarily verify that the DNS record is correct, only that one exists. For additional troubleshooting you could do reverse DNS lookup or verify IP address is correct. DNS query is sent to the IP address of DNS server configured on local machine (/etc/resolv.conf) for Linux. Common issues include misconfigured or missing DNS records (A, AAAA, CNAME) and DNS propagation delays after recent changes. There is also misspelled or expired domain names that will cause DNS failure.

✅ If you see authoritative or non-authoritative answers then DNS has resolved hostname.
❌ If you get a “NXDOMAIN” or timeout, there is a DNS configuration error or server is offline.

Connectivity Test

Verify basic connectivity between the local machine and the API endpoint to confirm it is reachable. This diagnostic test uses curl command to verify that API endpoint used with DNS check is operational. Curl is preferred instead of ping command since firewall rule could block ICMP packets and prevent test execution. This is also a more reliable method for testing cloud APIs that typically do not allow ICMP traffic. Test from different locations since firewall filtering, network congestion, and other connectivity issues could vary.

✅ If curl connects successfully (no errors), it indicates good network connectivity and the API endpoint is reachable over HTTP/S.
❌ If curl fails to connect, it may indicate the server is offline, the endpoint URL is incorrect, firewall is blocking HTTP connections, or there is a network issue preventing access.

Traceroute

Check the network path from local machine to API endpoint to identify routing issues or bottlenecks. Traceroute command sends ICMP packets and logs the IP address of each router (hop) along the route to API endpoint. The results reveal if there are delays, packet drops, or unreachable routers that could be offline for example. This is useful for pinpointing latency issues within an ISP or internal network routing loops.

✅ Each hop shows the assigned IP address and latency.
❌ Timeouts or abrupt ends may indicate ICMP filtering, routing issues, or routers offline.

Open Port Check

Confirm that a firewall is not blocking HTTP/HTTPS application port (443, 80, 8080) and listening on server. The diagnostic test attempts to open a TCP connection to the user selected port based on IP address from ping test. The result confirms whether there is a firewall rule filtering an application port or server misconfiguration. This test permits user to test any server non-standard TCP port number.

✅ Connection succeeds message is returned when the server is listening on the selected application port and no firewall blocking.
❌ Connection timeouts occur when server is offline, overloaded, or firewall is filtering application port. Connection refused errors occur when application port is closed or a server misconfiguration.

SSL Certificate Check

Check SSL/TLS certificate validity period, expiry date, and number of days remaining. The diagnostic test connects over port 443 and inspects the SSL certificate presented by the server. Common issues such as expired SSL/TLS certificate compromise API security. In fact, when HSTS is enabled, an expired certificate would prevent access to an application since HTTPS is mandatory.

✅ Days remaining until expiration.
❌ Errors for expired, invalid, or unreachable certificate.

HTTP Server Status Check

Verify that HTTP service is running on the server and detect response code. Test sends HTTP GET request (method) to the web server based on API endpoint used with DNS check. The purpose of this test is to detect specific error codes returned by server when troubleshooting application issues.

200 OK: ✅ Normal operation
301/302: Redirects
4xx: ❌ Client error (e.g., 404 not found, 403 forbidden, 400 bad request etc.)
5xx: ❌ Server error (e.g., 500 internal server error, 503 service unavailable, 504 bad gateway)

Status	Error Name	Common Root Causes / Examples
400	Bad Request	Malformed URL or JSON, Missing required fields, Invalid query parameters
401	Unauthorized	Missing or invalid API token, No Authorization header, User not authenticated
403	Forbidden	Insufficient permissions, IP blocked, Access control restrictions
404	Not Found	Incorrect URL, Resource removed, File or page doesn’t exist
405	Method Not Allowed	POST on GET-only route, Unsupported method, Misconfigured API
408	Request Timeout	Client took too long, Server timed out, Slow connection
409	Conflict	Duplicate resource, Version conflict, Simultaneous edits
429	Too Many Requests	Rate limit exceeded, API throttling, Bot activity
500	Internal Server Error	Code bugs, Crash in backend, Misconfigured server
501	Not Implemented	Feature not available, Method not supported, Stub endpoint
502	Bad Gateway	Upstream server failure, Reverse proxy issue, DNS failure
503	Service Unavailable	Overloaded server, Maintenance mode, Rate limiting
504	Gateway Timeout	Backend too slow, DB query timeout, Load balancer delay
505	HTTP Version Not Supported	Old HTTP version, Client incompatibility, Legacy tool in use

Check HTTP Headers

Sends an HTTP request to the specified domain to fetch response headers from server. The server responds with headers that are based on server configuration and operational state. The diagnostic test also analyzes security headers and calculates a score based on six recommended security features. HTTP header check is used to detect web server configuration settings that are key to troubleshooting web applications.

Identify server software (Server, X-Powered-By)
Check caching behavior (Cache-Control, ETag, Expires)
Content settings (Content-Type, Content-Encoding)
Authentication token, key, basic (WWW-Authenticate)
Server overload or rate limiting (Retry-After)
Request tracing for log correlation (X-Request-ID)
Debugging reverse proxies (Via, X-Forwarded-For)

API Application Latency

Measure the API endpoint response time by sending a single GET request and calculating latency (seconds). This diagnostic test helps detect performance issues due to server load, network congestion, or geographic distance. The fully qualified API endpoint entered for DNS check (e.g., https://api.example.com/v1/status) is used. Common performance issues may include unoptimized database queries, network congestion, or CDN misconfiguration.

✅ Average response time below 100 ms is considered normal.
❌ Latency above 150 ms may indicate server overload, backend bottlenecks, or network delays.

Authentication Check

This diagnostic test verifies API endpoint authentication and whether the provided credentials are working. The user is prompted to enter an API key, bearer token, or basic (username/password) depending on the endpoint configuration. The tool sends an authenticated request and checks the HTTP response code. Authentication check helps diagnose incorrect API token, keys, expired or revoked credentials, misconfigured identity, or access policies. There is also an option to skip authentication test if not applicable.

✅ 200 OK or 204 No Content means authentication succeeded.
❌ 401 Unauthorized or 403 Forbidden indicates missing, expired, or invalid credentials.

CORS Check

CORS (Cross-Origin Resource Sharing) errors are common when APIs are accessed from browsers. This test simulates a browser-originated request using curl with custom Origin headers to determine if the API endpoint supports cross-origin access. It checks for the presence and configuration of CORS response headers. This is useful when debugging web applications that consume external APIs and are experiencing browser CORS failures. The diagnostic test checks for the following headers:

Access-Control-Allow-Origin
Access-Control-Allow-Methods
Access-Control-Allow-Headers
Access-Control-Allow-Credentials

✅ Access-Control-Allow-Origin: or matching domain in response indicates proper CORS configuration.
❌ Missing or incorrect CORS headers may cause browser requests to fail with CORS policy errors.

HTML Report Generation

Once all diagnostics are complete, the application automatically generates an HTML report if you selected this option at start of test. The report includes all test results, clearly marked with ✅ (success) or ❌ (failure). Reports are saved to your local working directory with a filename based on the API domain name (e.g., example.com.html). You can easily share them with colleagues or use them for documentation.

User prompt to generate HTML report format.
Each test is marked with ✅ (success) or ❌ (failure).
Saved locally (e.g., example.com.html).
Attach to email for troubleshooting collaboration, testing, and production deployment.

Custom Freeware License and Disclaimer

This software (API Troubleshooter) is provided free of charge for personal and non-commercial use only, subject to the following terms:

Permissions
You may redistribute copies of this software, provided that you retain the copyright notice and this license in all copies. You may use this software on your personal Linux system for non-commercial purposes.

Restrictions
You may not sell, sublicense, or otherwise distribute this software for commercial purposes. You may not modify, reverse-engineer, or decompile this software, unless explicitly permitted by the author. Any redistribution of the software must retain this license, and the software must not be distributed with commercial intent or for profit.

No Warranty
This software is provided “as-is”, without any warranty of any kind, either express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, or non-infringement. In no event shall the author be liable for any damages arising from the use or misuse of this software. Use at your own risk. Be sure to review the generated reports carefully, as they may contain sensitive system information.