Website Connectivity Diagnostics API

A simple API for DNS, TCP, TLS, and HTTPS health checks built for developers.

原始信息汇总

Website Connectivity Diagnostics API 数据集概述

基本信息

• API名称: Website Connectivity Diagnostics API
• 提供商: xakpc
• 类别: Monitoring
• 状态: Free
• 流行度: 8.6
• 服务等级: 100%
• 延迟: 1275ms
• 测试通过率: 100%
• 官方网站: https://netdiag.dev
• 文档地址: https://netdiag.dev/docs

核心功能

提供全面的网站网络诊断服务，支持实时健康检查。

• ICMP Ping: 测量延迟和可达性。
• DNS解析: 使用自定义DNS服务器验证名称解析。
• TLS/SSL验证: 检查证书有效性和过期时间。
• HTTP/HTTPS检查: 测试Web服务可用性和响应时间。

主要端点

• 端点: GET /v1/checks
• 功能: 对一个目标主机名或IP地址跨一个或多个地理区域执行全面的网络诊断。

请求参数

参数	类型	必需	默认值	描述
target	string	是	-	要检查的主机名或IP地址
regions	string	否	所有区域	逗号分隔的区域代码（例如：us-east,eu-west）
port	int	否	443	要检查的端口。允许值：80, 443, 8080, 8443
pingCount	int	否	4	Ping数据包数量（1-100）
pingTimeout	int	否	5	Ping超时时间（秒）（1-30）
dns	string	否	系统DNS	自定义DNS服务器（IPv4、IPv6或主机名）
format	string	否	json	响应格式：json 或 prometheus

检查类型

每个请求对目标运行四种诊断检查：

检查	功能描述
Ping	测量延迟（平均/最小/最大RTT）和数据包丢失。如果ICMP被阻止，则回退到TCP。
DNS	将主机名解析为IP地址。支持自定义DNS服务器。
TLS	验证证书链、过期时间和协议版本。
HTTP	测试HTTP/HTTPS连接，捕获状态码和响应时间。

状态值

每个检查返回以下三种状态之一：

状态	含义
Healthy	检查通过
Warning	正常工作但需要注意（例如，证书在<30天内过期，响应时间>3秒）
Unhealthy	检查失败（超时、连接被拒绝、证书过期、DNS失败）

整体 status 反映所有检查和区域中最差的状态。

响应格式

响应使用交通灯模型：

• Healthy - 所有检查通过
• Warning - 正常工作但需要注意
• Unhealthy - 不工作或失败

示例响应（JSON格式）

json { "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "target": "github.com", "status": "Healthy", "quorum": "2/2", "dnsPropagationStatus": "consistent", "startedAt": "2025-01-05T10:30:00Z", "completedAt": "2025-01-05T10:30:03Z", "locations": [ { "region": "us-east", "status": "Healthy", "ping": { ... }, "dns": { ... }, "tls": { ... }, "http": { ... } } ] }

Prometheus 指标

添加 format=prometheus 以获取Prometheus公开格式的指标。

• 请求示例: GET /v1/checks?target=example.com&format=prometheus
• 返回格式: text/plain

指标列表

指标	描述
netdiag_check_success	检查是否成功（1=健康，0=不健康）
netdiag_ping_latency_ms	Ping往返时间（毫秒）
netdiag_ping_loss_percent	Ping数据包丢失百分比
netdiag_http_status	HTTP响应状态码
netdiag_http_latency_ms	HTTP响应时间（毫秒）
netdiag_tls_valid	TLS证书有效性（1=有效，0=无效）
netdiag_tls_days_remaining	TLS证书到期前的天数
netdiag_dns_addresses_count	解析的DNS地址数量

所有指标都包含 target 和 region 标签。

速率限制

层级	限制	识别方式
Free	10 次请求/分钟	无API密钥
Signed	60 次请求/分钟	X-API-Key 请求头

速率限制超出响应（429）示例: json { "type": "https://tools.ietf.org/html/rfc9110#section-15.5.30", "title": "Too Many Requests", "status": 429, "detail": "Rate limit exceeded. Register on https://netdiag.dev to obtain an API key.", "rateLimit": { "tier": "free", "limit": 10, "resetInSeconds": 60 } }

错误处理

错误代码范围

范围	类别	示例
100-199	常规错误	超时、未知错误
200-299	Ping错误	无响应、ICMP被阻止、主机不可达
300-399	DNS错误	NXDOMAIN、超时、无记录
400-499	TLS错误	连接失败、证书过期、握手失败
500-599	HTTP错误	连接失败、超时、连接被拒绝

HTTP状态码

代码	含义
200	检查完成（如果某些区域失败，响应可能包含部分结果）
400	参数无效（错误的目标、无效的区域、不支持的端口）
429	超出速率限制
503	所有探测失败

客户端库

.NET

• 包管理器: dotnet add package Xakpc.NetDiag.Client
• 支持环境: .NET 8/9，依赖注入，ASP.NET Core集成
• 文档: https://netdiag.dev/docs

JavaScript / TypeScript

• 包管理器: npm install @netdiag/client
• 支持环境: Node.js 18+ 和现代浏览器，包含完整的TypeScript支持
• 文档: https://netdiag.dev/docs

Python

• 包管理器: pip install netdiag-client
• 要求: Python 3.10+，基于httpx构建，包含完整的类型提示
• 文档: https://netdiag.dev/docs

其他端点

探测状态端点

• 端点: GET /v1/probes/status
• 功能: 检查可用探测区域的健康状况。

使用示例

快速开始

bash

从所有区域检查网站

curl "https://api.netdiag.dev/v1/checks?target=example.com"

检查特定区域

curl "https://api.netdiag.dev/v1/checks?target=example.com&regions=us-east,eu-west"

获取Prometheus指标

curl "https://api.netdiag.dev/v1/checks?target=example.com&format=prometheus"

监控证书过期

bash

检查证书是否在30天内过期

curl -s "https://api.netdiag.dev/v1/checks?target=yourdomain.com" | jq .locations[0].tls.daysUntilExpiry

验证DNS传播

bash

检查DNS是否在各个区域一致解析

curl -s "https://api.netdiag.dev/v1/checks?target=yourdomain.com" | jq {status: .dnsPropagationStatus, addresses: [.locations[].dns.resolvedAddresses]}

Bash健康检查脚本

bash #!/bin/bash RESULT=$(curl -s "https://api.netdiag.dev/v1/checks?target=$1") STATUS=$(echo "$RESULT" | jq -r .status)

if [ "$STATUS" = "Healthy" ]; then echo "OK: $1 is healthy" exit 0 elif [ "$STATUS" = "Warning" ]; then echo "WARNING: $1 needs attention" exit 1 else echo "CRITICAL: $1 is unhealthy" exit 2 fi