API 文档

短链平台 RESTful API 接口文档

一、基本介绍

短链平台提供简单易用的 RESTful API 接口，允许开发者通过 HTTP 请求创建和管理短链接。

基础 URL：https://yoursite.com/api

数据格式：JSON

字符编码：UTF-8

二、功能说明

功能	接口	方法	描述
创建短链	`/api/shortlink`	POST	为长链接生成短链接
删除短链	`/api/shortlink/{shortCode}`	DELETE	删除指定的短链接（仅限自己创建的）

三、认证方式

所有 API 接口都需要使用 App Key 进行身份验证。

获取 App Key：

登录管理员账号
导航到"API 应用"管理页面
创建新的 API 应用
妥善保存生成的 App ID 和 App Key（格式：app_xxxxxxxxxxxx）

使用方式：

在 HTTP 请求头中添加 App Key：

X-API-Key: your_app_key_here

注意：App Key 是敏感信息，请妥善保管，不要泄露给他人。

四、API 接口详情

1. 创建短链

请求信息

方法	POST
路径	`/api/shortlink`
Content-Type	`application/json`
认证	需要 App Key

请求头

参数名	类型	必填	说明
X-API-Key	string	是	App Key
Content-Type	string	是	固定值：application/json

请求参数

参数名	类型	必填	说明	示例
originalUrl	string	是	原始长链接	https://example.com/long/url
expiresAt	string (ISO 8601)	否	过期时间（留空则永不过期）	2026-01-08T14:30:00

请求示例

curl -X POST https://yoursite.com/api/shortlink \
  -H "X-API-Key: your_app_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "originalUrl": "https://example.com/very/long/url",
    "expiresAt": "2026-01-08T14:30:00"
  }'

const response = await fetch('https://yoursite.com/api/shortlink', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_app_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    originalUrl: 'https://example.com/very/long/url',
    expiresAt: '2026-01-08T14:30:00'
  })
});

成功响应

状态码：200 OK

{
  "message": "创建短链成功",
  "data": {
    "shortCode": "NbpIUq",
    "shortUrl": "https://yoursite.com/NbpIUq"
  }
}

错误响应

状态码：401 Unauthorized

{
  "message": "缺少 API Key"
}

状态码：401 Unauthorized

{
  "message": "无效的 API Key"
}

状态码：400 Bad Request

{
  "message": "请求参数无效"
}

2. 删除短链

请求信息

方法	DELETE
路径	`/api/shortlink/{shortCode}`
认证	需要 App Key

路径参数

参数名	类型	必填	说明
shortCode	string	是	要删除的短链码

请求示例

curl -X DELETE https://yoursite.com/api/shortlink/NbpIUq \
  -H "X-API-Key: your_app_key_here"

const response = await fetch('https://yoursite.com/api/shortlink/NbpIUq', {
  method: 'DELETE',
  headers: {
    'X-API-Key': 'your_app_key_here'
  }
});

成功响应

状态码：200 OK

{
  "message": "删除成功"
}

错误响应

状态码：401 Unauthorized

{
  "message": "缺少 API Key"
}

状态码：403 Forbidden

{
  "message": "无权删除此短链"
}

状态码：404 Not Found

{
  "message": "短链不存在"
}

五、常见问题

A1: 需要联系管理员申请 API 应用。管理员登录后在"API 应用"管理页面创建新的应用，您将获得 App ID 和 App Key。

A2: 当前版本不限制调用次数，您可以根据需要自由调用 API 接口。每个 App Key 对应一个应用。

A3: 默认永不过期。您可以在创建短链时指定过期时间，过期的短链将无法访问。

A4: 当前版本不支持更新短链。如果需要修改，请删除旧短链后重新创建。

A5: 只能删除由您的 App Key 创建的短链，无法删除其他应用或平台创建的短链。

A6: 当前版本不限制调用次数，您可以根据需要自由调用 API 接口。每个 App Key 对应一个应用。

A7: 请立即联系管理员，删除泄露的应用并创建新的 App Key。不要将 App Key 提交到代码仓库或公开的文档中。

六、完整代码示例

Python 示例

import requests

# 创建短链
url = "https://yoursite.com/api/shortlink"
headers = {
    "X-API-Key": "your_app_key_here",
    "Content-Type": "application/json"
}
data = {
    "originalUrl": "https://example.com/very/long/url",
    "expiresAt": "2026-01-08T14:30:00"
}

response = requests.post(url, json=data, headers=headers)
result = response.json()

if result["success"]:
    print(f"短链: {result['shortUrl']}")
else:
    print(f"错误: {result['message']}")

# 删除短链
delete_url = "https://yoursite.com/api/shortlink/NbpIUq"
delete_response = requests.delete(delete_url, headers=headers)
delete_result = delete_response.json()

if delete_result["success"]:
    print("删除成功")
else:
    print(f"删除失败: {delete_result['message']}")

JavaScript (Fetch) 示例

async function createShortLink(originalUrl, expiresAt) {
    const response = await fetch('https://yoursite.com/api/shortlink', {
        method: 'POST',
        headers: {
            'X-API-Key': 'your_app_key_here',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            originalUrl,
            expiresAt
        })
    });

    const result = await response.json();

    if (result.success) {
        console.log('短链:', result.shortUrl);
        return result.shortUrl;
    } else {
        console.error('错误:', result.message);
        throw new Error(result.message);
    }
}

async function deleteShortLink(shortCode) {
    const response = await fetch(`https://yoursite.com/api/shortlink/${shortCode}`, {
        method: 'DELETE',
        headers: {
            'X-API-Key': 'your_app_key_here'
        }
    });

    const result = await response.json();

    if (result.success) {
        console.log('删除成功');
    } else {
        console.error('删除失败:', result.message);
        throw new Error(result.message);
    }
}

// 使用示例
createShortLink('https://example.com/very/long/url', '2026-01-08T14:30:00')
    .then(shortUrl => console.log('创建成功:', shortUrl))
    .catch(error => console.error('创建失败:', error.message));

// 删除短链
deleteShortLink('NbpIUq')
    .catch(error => console.error('删除失败:', error.message));

C# 示例

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class ShortLinkClient
{
    private readonly HttpClient _httpClient;
    private const string AppKey = "your_app_key_here";
    private const string BaseUrl = "https://yoursite.com/api/shortlink";

    public ShortLinkClient()
    {
        _httpClient = new HttpClient();
        _httpClient.DefaultRequestHeaders.Add("X-API-Key", AppKey);
    }

    public async Task CreateShortLinkAsync(string originalUrl, string? expiresAt = null)
    {
        var requestData = new
        {
            originalUrl,
            expiresAt
        };

        var json = JsonSerializer.Serialize(requestData);
        var content = new StringContent(json, Encoding.UTF8, "application/json");

        var response = await _httpClient.PostAsync(BaseUrl, content);
        var responseContent = await response.Content.ReadAsStringAsync();

        var result = JsonSerializer.Deserialize(responseContent);

        if (result.Success)
        {
            return result.ShortUrl;
        }
        else
        {
            throw new Exception(result.Message);
        }
    }

    public async Task DeleteShortLinkAsync(string shortCode)
    {
        var response = await _httpClient.DeleteAsync($"{BaseUrl}/{shortCode}");
        var responseContent = await response.Content.ReadAsStringAsync();

        var result = JsonSerializer.Deserialize(responseContent);

        if (!result.Success)
        {
            throw new Exception(result.Message);
        }
    }
}

public class CreateShortLinkResponse
{
    public bool Success { get; set; }
    public string ShortCode { get; set; }
    public string ShortUrl { get; set; }
    public string Message { get; set; }
}

public class DeleteShortLinkResponse
{
    public bool Success { get; set; }
    public string Message { get; set; }
}

// 使用示例
var client = new ShortLinkClient();
try
{
    var shortUrl = await client.CreateShortLinkAsync("https://example.com/very/long/url");
    Console.WriteLine($"短链: {shortUrl}");

    // 删除短链
    await client.DeleteShortLinkAsync("NbpIUq");
}
catch (Exception ex)
{
    Console.WriteLine($"错误: {ex.Message}");
}

API 文档

一、基本介绍

二、功能说明

三、认证方式

获取 App Key：

使用方式：

四、API 接口详情

1. 创建短链

请求信息

请求头

请求参数

请求示例

成功响应

错误响应

2. 删除短链

请求信息

路径参数

请求示例

成功响应

错误响应

五、常见问题

Q1: 如何获取 API Key？

Q2: 当前版本是否限制调用次数？

Q3: 短链的有效期是多长？

Q4: 可以更新或修改已创建的短链吗？

Q5: 删除短链时有什么限制？

Q6: 当前版本是否限制调用次数？

Q7: 如果 App Key 泄露了怎么办？

六、完整代码示例

Python 示例

JavaScript (Fetch) 示例

C# 示例