-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathapi-docs.html
More file actions
242 lines (229 loc) · 13.2 KB
/
Copy pathapi-docs.html
File metadata and controls
242 lines (229 loc) · 13.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="theme-color" content="#eef0ec" />
<meta name="description" content="终末地版本日历公开活动 API 完整接口说明" />
<title>公开活动 API · 终末地版本日历</title>
<script src="./theme.js"></script>
<link rel="stylesheet" href="./api-docs.css" />
<link rel="stylesheet" href="./theme.css" />
</head>
<body>
<header class="docs-header">
<nav class="docs-topbar" aria-label="API 文档导航">
<a class="docs-brand" href="./index.html" aria-label="返回终末地版本日历">
<span class="docs-brand-mark">EF</span>
<span><strong>ENDFIELD</strong><small>PUBLIC API</small></span>
</a>
<div class="docs-actions">
<a href="./index.html">返回日历</a>
<a href="https://github.com/MoguJunn/endfield-version-calendar" target="_blank" rel="noopener noreferrer">GitHub ↗</a>
<div class="theme-picker" data-theme-picker>
<button class="theme-trigger" type="button" aria-haspopup="menu" aria-expanded="false" aria-label="主题：跟随系统" data-theme-trigger>
<span aria-hidden="true" data-theme-icon>▣</span>
<span class="visually-hidden" data-theme-label>主题：跟随系统</span>
</button>
<div class="theme-menu" role="menu" aria-label="选择主题">
<button class="theme-option" type="button" role="menuitemradio" aria-checked="true" data-theme-option="system"><span class="theme-option-icon" aria-hidden="true">▣</span><span>跟随系统</span></button>
<button class="theme-option" type="button" role="menuitemradio" aria-checked="false" data-theme-option="light"><span class="theme-option-icon" aria-hidden="true">☀</span><span>亮色</span></button>
<button class="theme-option" type="button" role="menuitemradio" aria-checked="false" data-theme-option="dark"><span class="theme-option-icon" aria-hidden="true">☾</span><span>暗色</span></button>
</div>
</div>
</div>
</nav>
<div class="docs-hero">
<p class="docs-kicker">VERSION 1 · PUBLIC API</p>
<h1>公开活动 API</h1>
<p>获取日历页面使用的最终合并数据，包括人工整理活动、版本快照、角色寻访和武库申领。</p>
<div class="endpoint-line" aria-label="生产接口地址">
<strong>GET</strong>
<code>https://ef-cal.mogujun.icu/api/v1/events</code>
</div>
<div class="download-actions">
<a class="button primary" href="./openapi.json" download="endfield-calendar-openapi.json">下载 OpenAPI JSON ↓</a>
<a class="button" href="./docs/API.md" download="endfield-calendar-api.md">下载 Markdown ↓</a>
<a class="button" href="https://ef-cal.mogujun.icu/api/v1/events" target="_blank" rel="noopener noreferrer">查看实时响应 ↗</a>
</div>
</div>
</header>
<div class="docs-layout">
<aside class="docs-toc" aria-label="文档目录">
<strong>接口说明</strong>
<a href="#overview">概览</a>
<a href="#quick-start">快速调用</a>
<a href="#parameters">查询参数</a>
<a href="#success">成功响应</a>
<a href="#fields">事件字段</a>
<a href="#errors">错误响应</a>
<a href="#rate-limit">请求频率限制</a>
<a href="#cache">缓存与实时状态</a>
<a href="#sources">来源与免责声明</a>
</aside>
<main class="docs-content">
<section id="overview">
<p class="section-label">01 / OVERVIEW</p>
<h2>概览</h2>
<p>该接口只读、免密，并返回 <code>Access-Control-Allow-Origin: *</code>。浏览器、服务端程序和命令行工具都可以直接调用，无需 Cookie 或 API Key。</p>
<div class="callout">
<strong>稳定版本契约</strong>
<p>当前 API 版本为 <code>1</code>。调用方应同时检查 HTTP 状态码、顶层 <code>success</code> 与 <code>apiVersion</code>。</p>
</div>
</section>
<section id="quick-start">
<p class="section-label">02 / QUICK START</p>
<h2>快速调用</h2>
<h3>命令行</h3>
<pre><code>curl "https://ef-cal.mogujun.icu/api/v1/events?version=5&status=live"</code></pre>
<h3>浏览器 JavaScript</h3>
<pre><code>const response = await fetch(
"https://ef-cal.mogujun.icu/api/v1/events?category=operator,limited&status=upcoming",
);
const payload = await response.json();
if (!payload.success) throw new Error(payload.error.message);
console.log(payload.data.events);</code></pre>
</section>
<section id="parameters">
<p class="section-label">03 / QUERY</p>
<h2>查询参数</h2>
<div class="table-scroll">
<table>
<thead><tr><th>参数</th><th>默认值</th><th>说明</th></tr></thead>
<tbody>
<tr><td><code>version</code></td><td><code>all</code></td><td><code>all</code>、版本键（如 <code>version-5</code>）或版本号（如 <code>5</code>）</td></tr>
<tr><td><code>category</code></td><td><code>all</code></td><td>逗号分隔的 <code>operator</code>、<code>arsenal</code>、<code>permanent</code>、<code>limited</code>、<code>update</code></td></tr>
<tr><td><code>status</code></td><td><code>all</code></td><td><code>all</code>、<code>upcoming</code>、<code>live</code>、<code>ended</code></td></tr>
<tr><td><code>from</code></td><td>无</td><td>带时区的 RFC 3339 时间；查询区间起点（包含）</td></tr>
<tr><td><code>to</code></td><td>无</td><td>带时区的 RFC 3339 时间；查询区间终点（不包含）</td></tr>
</tbody>
</table>
</div>
<p><code>category</code> 可以组合，例如 <code>?category=operator,arsenal</code>。时间筛选采用区间相交语义，而不是只比较活动开始时间。</p>
<p>没有确定结束时间的常驻活动会被视为持续开放；单次更新节点只在其发生时刻与查询区间相交。参数非法、版本不存在或 <code>from</code> 不早于 <code>to</code> 时返回 HTTP 400。</p>
</section>
<section id="success">
<p class="section-label">04 / RESPONSE</p>
<h2>成功响应</h2>
<pre><code>{
"success": true,
"apiVersion": "1",
"generatedAt": "2026-07-12T00:00:00.000Z",
"timeZone": "Asia/Shanghai",
"source": {
"mode": "origin",
"partial": false,
"updatedAt": "2026-07-11T18:16:32.446Z"
},
"data": {
"activeVersionKey": "version-5",
"versions": [],
"events": []
},
"meta": {
"total": 0,
"filters": {
"version": "all",
"categories": ["all"],
"status": "all",
"from": null,
"to": null
}
}
}</code></pre>
<h3>数据来源状态</h3>
<div class="table-scroll">
<table>
<thead><tr><th><code>source.mode</code></th><th>含义</th></tr></thead>
<tbody>
<tr><td><code>origin</code></td><td>主站版本快照读取成功，并与日历仓库人工活动合并</td></tr>
<tr><td><code>partial</code></td><td>只取得部分上游数据，缺失部分已由本地数据补齐</td></tr>
<tr><td><code>fallback</code></td><td>上游不可用，完整使用仓库内置版本与活动数据</td></tr>
</tbody>
</table>
</div>
<p>调用方不应只根据 HTTP 200 判断数据是否来自上游，还应检查 <code>source.mode</code> 和 <code>source.partial</code>。</p>
</section>
<section id="fields">
<p class="section-label">05 / EVENT FIELDS</p>
<h2>事件字段</h2>
<div class="table-scroll">
<table>
<thead><tr><th>字段</th><th>说明</th></tr></thead>
<tbody>
<tr><td><code>id</code></td><td>稳定事件 ID</td></tr>
<tr><td><code>versionKey</code></td><td>事件所属版本键</td></tr>
<tr><td><code>poolId</code></td><td>对应主站卡池 ID；非卡池活动为 <code>null</code></td></tr>
<tr><td><code>category</code></td><td>活动分类</td></tr>
<tr><td><code>title</code> / <code>related</code></td><td>活动标题及配套签到、作战演练等关联内容</td></tr>
<tr><td><code>start</code> / <code>end</code></td><td>ISO 8601 时间；未知或开放式结束为 <code>null</code></td></tr>
<tr><td><code>status</code></td><td><code>upcoming</code>、<code>live</code> 或 <code>ended</code></td></tr>
<tr><td><code>startUnknown</code></td><td><code>start</code> 是否仅为时间轴定位锚点</td></tr>
<tr><td><code>startLabel</code> / <code>endLabel</code></td><td>未确定或相对时间的展示说明</td></tr>
<tr><td><code>permanent</code> / <code>milestone</code></td><td>是否为常驻内容或单次更新节点</td></tr>
<tr><td><code>overlayFor</code></td><td>更新节点所依附的活动 ID</td></tr>
<tr><td><code>image</code></td><td>可直接访问的绝对图片 URL，或 <code>null</code></td></tr>
<tr><td><code>color</code> / <code>eventInk</code></td><td>时间轴背景色与建议文字色</td></tr>
<tr><td><code>description</code> / <code>sourceNote</code></td><td>活动说明、数据来源或不确定性说明</td></tr>
</tbody>
</table>
</div>
<p>排轨位置、浏览器 <code>Date</code> 对象和数据库管理字段不会公开。</p>
</section>
<section id="errors">
<p class="section-label">06 / ERRORS</p>
<h2>错误响应</h2>
<pre><code>{
"success": false,
"apiVersion": "1",
"error": {
"code": "INVALID_QUERY",
"message": "查询参数无效",
"details": []
}
}</code></pre>
<div class="table-scroll">
<table>
<thead><tr><th>HTTP 状态</th><th>场景</th></tr></thead>
<tbody>
<tr><td><code>400</code></td><td>查询参数非法</td></tr>
<tr><td><code>405</code></td><td>使用了 GET、OPTIONS 之外的方法</td></tr>
<tr><td><code>429</code></td><td>同一客户端在限速窗口内请求过多</td></tr>
<tr><td><code>500</code></td><td>服务端发生无法通过本地数据恢复的错误</td></tr>
</tbody>
</table>
</div>
<p>上游主站超时或暂时不可用通常不会返回 502；接口会使用仓库内置数据，并通过 <code>source.mode: "fallback"</code> 告知调用方。</p>
</section>
<section id="rate-limit">
<p class="section-label">07 / RATE LIMIT</p>
<h2>请求频率限制</h2>
<p>接口默认按客户端 IP 提供每 60 秒 60 次函数请求的基础保护。超过限额时返回 HTTP 429 和错误代码 <code>RATE_LIMITED</code>：</p>
<pre><code>HTTP/1.1 429 Too Many Requests
Retry-After: 42
RateLimit-Limit: 60
RateLimit-Remaining: 0
Cache-Control: no-store</code></pre>
<p>跨域预检 <code>OPTIONS</code> 不占额度。由 ESA 或 Vercel CDN 直接命中的缓存响应通常不会进入函数，也不会消耗函数内额度。当前限制在每个 Vercel 函数实例内独立计数，用于抑制突发请求，并非跨全部实例的严格全局配额。</p>
</section>
<section id="cache">
<p class="section-label">08 / CACHE</p>
<h2>缓存与实时状态</h2>
<pre><code>Cache-Control: public, max-age=0, s-maxage=60, stale-while-revalidate=300</code></pre>
<p>共享 CDN 可缓存成功响应 60 秒，并在后台重新验证期间短暂使用旧响应。因此 <code>status</code> 通常最多可能相对请求时刻延迟约一分钟；需要临界秒级精度时，应根据事件时间字段自行重新计算。</p>
<p>所有错误响应（400、405、429 和 500）均使用 <code>no-store</code>，避免 CDN 缓存临时错误或限速结果。</p>
</section>
<section id="sources">
<p class="section-label">09 / SOURCES</p>
<h2>数据来源与免责声明</h2>
<p>规范版本与卡池信息来自抽卡主站公开接口；人工活动主要依据罗德岛蜜饼工坊发布的「向渊行」非官方活动时间轴整理。</p>
<p>接口是社区维护的非官方服务，与鹰角网络、峘形山工作室及相关权利方不存在隶属、授权或背书关系。若接口内容与官方公告或游戏内显示不一致，请以官方信息为准；调用方展示数据时应保留适当的非官方说明和来源信息。</p>
</section>
</main>
</div>
<footer class="docs-footer">
<span>ARKNIGHTS: ENDFIELD · COMMUNITY CALENDAR API</span>
<a href="./index.html">返回版本日历</a>
</footer>
</body>
</html>