API接口文档

完整的API接口使用指南，包含调用方式、参数说明、响应格式和错误处理。

文档导航

API概述

我们的API服务提供了一系列功能接口，帮助您快速集成到您的应用程序中。所有API都采用RESTful设计，支持JSON格式的请求和响应。

基本特性

  • RESTful API设计，遵循标准HTTP方法
  • JSON格式请求和响应
  • 支持HTTPS加密传输
  • 详细的错误码和消息
  • 完整的API文档和示例
  • 多语言SDK支持
  • 7x24小时技术支持

基础URL

https://api.example.com/

重要提示

所有API调用都需要使用HTTPS协议，确保数据传输的安全性。请勿使用HTTP协议访问API接口。

快速开始

以下是一个简单的API调用示例，帮助您快速了解如何使用我们的API服务。

步骤1：获取API密钥

在调用API之前，您需要先注册账号并获取API密钥。登录后，在控制台的API密钥管理页面可以生成您的专属API密钥。

步骤2：构造API请求

所有API请求都需要包含API密钥作为身份验证。以下是调用示例：

示例请求 
GET /api/icp?apikey=您的API密钥&url=example.com HTTP/1.1
Host: api.example.com
Content-Type: application/json

步骤3：处理API响应

API响应将返回JSON格式的数据，包含请求结果和相关信息。

示例响应 
{
    "code": 0,
    "message": "success",
    "data": {
        "url": "example.com",
        "icp": "京ICP备12345678号",
        "company": "示例公司",
        "type": "企业备案",
        "verify_time": "2023-01-01"
    },
    "timestamp": 1672502400
}

身份认证

所有API请求都需要进行身份验证。我们使用API密钥的方式进行认证。

API密钥认证

在每个API请求的URL参数中包含apikey参数：

https://api.example.com/api/接口名称?apikey=您的API密钥&其他参数...

安全建议

  • 不要将API密钥提交到版本控制系统（如Git）
  • 不要在客户端代码中暴露API密钥
  • 定期轮换API密钥以提高安全性
  • 为不同的应用使用不同的API密钥

安全警告

API密钥是访问您账户的凭证，请妥善保管。如果发现密钥泄露，请立即在控制台中禁用该密钥并生成新的密钥。

API端点

以下是主要的API端点列表，详细的接口文档可以在各个接口的详情页面查看。

接口名称 端点 方法 描述
用户信息查询 /api/v1/users/{id} GET 根据用户ID查询用户详细信息
创建订单 /api/v1/orders POST 创建新的订单
数据统计 /api/v1/analytics GET 获取数据统计分析报告
文件上传 /api/v1/files/upload POST 上传文件到云端存储
ICP备案查询 /api/icp GET 查询网站的ICP备案信息
IP地理位置 /api/ip GET 查询IP地址的地理位置信息

请求参数

URL参数

大多数GET请求使用URL参数传递数据：

URL参数示例 
GET /api/icp?apikey=sk_1234567890abcdef&url=baidu.com&detail=true

请求体参数

POST、PUT、PATCH请求通常使用JSON格式的请求体：

JSON请求体示例 
{
    "name": "测试用户",
    "email": "test@example.com",
    "phone": "13800138000",
    "address": "北京市海淀区"
}

常见参数说明

参数名 类型 必需 描述
apikey 字符串 是 API密钥，用于身份验证
page 整数 否 页码，用于分页查询，默认为1
limit 整数 否 每页数据量，默认为20，最大100
order 字符串 否 排序字段，格式：字段名 排序方式，如：id DESC

响应格式

成功响应

所有成功的API请求都会返回JSON格式的响应，包含以下字段：

成功响应结构 
{
    "code": 0,
    "message": "success",
    "data": {
        // 接口返回的具体数据
    },
    "timestamp": 1672502400
}

分页响应

对于列表接口，返回的数据会包含分页信息：

分页响应结构 
{
    "code": 0,
    "message": "success",
    "data": {
        "list": [
            // 数据列表
        ],
        "pagination": {
            "total": 100,     // 总记录数
            "page": 1,        // 当前页码
            "limit": 20,      // 每页数量
            "pages": 5        // 总页数
        }
    },
    "timestamp": 1672502400
}

错误处理

错误响应格式

当API请求发生错误时，会返回相应的错误信息：

错误响应结构 
{
    "code": 1001,
    "message": "API密钥无效",
    "data": null,
    "timestamp": 1672502400
}

常见错误码

错误码 HTTP状态码 描述
0 200 成功
1001 401 API密钥无效或已过期
1002 403 权限不足，无法访问该资源
1003 400 请求参数无效或缺失
1004 404 请求的资源不存在
1005 429 请求频率超过限制
5000 500 服务器内部错误

频率限制

为保障API服务的稳定性和公平性，我们对API调用设置了频率限制。

限制规则

套餐类型 频率限制 说明
免费版 100次/小时 适合个人开发者和小规模应用
专业版 1000次/小时 适合中小型企业应用
企业版 10000次/小时 适合大规模企业应用

超出限制

当API调用频率超出限制时，会返回429状态码和错误码1005。建议您：

  • 合理设计API调用逻辑，避免不必要的请求
  • 使用缓存减少重复请求
  • 升级套餐以获得更高的调用频率

优化建议

对于需要频繁调用的数据，建议在客户端进行缓存，减少对API的重复请求。例如，可以将查询结果缓存5-10分钟。

调用示例

cURL示例

cURL 
curl -X GET \
  "https://api.example.com/api/icp?apikey=sk_1234567890abcdef&url=baidu.com" \
  -H "Content-Type: application/json"

Python示例

Python 
import requests

api_key = "sk_1234567890abcdef"
url = "https://api.example.com/api/icp"
params = {
    "apikey": api_key,
    "url": "baidu.com"
}

response = requests.get(url, params=params)
data = response.json()

if data["code"] == 0:
    print("查询成功:", data["data"])
else:
    print("查询失败:", data["message"])

JavaScript示例

JavaScript 
const apiKey = 'sk_1234567890abcdef';
const apiUrl = 'https://api.example.com/api/icp';

async function queryICP(domain) {
    const params = new URLSearchParams({
        apikey: apiKey,
        url: domain
    });

    try {
        const response = await fetch(`${apiUrl}?${params}`);
        const data = await response.json();

        if (data.code === 0) {
            console.log('查询成功:', data.data);
            return data.data;
        } else {
            console.error('查询失败:', data.message);
            return null;
        }
    } catch (error) {
        console.error('请求失败:', error);
        return null;
    }
}

// 使用示例
queryICP('baidu.com');

PHP示例

PHP 
$apiKey = 'sk_1234567890abcdef';
$domain = 'baidu.com';
$apiUrl = 'https://api.example.com/api/icp';

// 构造请求URL
$url = $apiUrl . '?' . http_build_query([
    'apikey' => $apiKey,
    'url' => $domain
]);

// 发送请求
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);

// 解析响应
$data = json_decode($response, true);

if ($data['code'] == 0) {
    echo '查询成功: ';
    print_r($data['data']);
} else {
    echo '查询失败: ' . $data['message'];
}

在线测试

您可以使用下面的表单测试API调用（模拟数据）：

常见问题

Q1: API密钥在哪里获取？

A: 登录后，在会员中心"个人"页面可以生成和管理API密钥。每个账户最多可以创建1个API密钥，。

Q2: 如何升级API调用频率限制？

A: 在控制台的"套餐管理"页面可以升级您的套餐。升级后，API调用频率限制会立即生效。

Q3: API响应时间一般是多少？

A: 大多数API接口的响应时间在100-500ms之间，具体取决于接口复杂度和当前服务器负载。

Q4: 支持HTTPS吗？

A: 是的，所有API都强制使用HTTPS协议，确保数据传输的安全性。

Q5: 如何获取技术支持？

A: 您可以通过以下方式获取技术支持：