|
|
@@ -0,0 +1,229 @@
|
|
|
1
|
+# Yico Website API Specification/前台 API 規格說明
|
|
|
2
|
+
|
|
|
3
|
+Version/版本:1.1(Verified against staging/已對 staging 實測驗證:2026-10-13;2026-10-21 圖片欄位改名)
|
|
|
4
|
+Machine-readable format/機器格式:see `openapi.yaml` in the same directory/同目錄 `openapi.yaml`
|
|
|
5
|
+
|
|
|
6
|
+## 1. Overview/總覽
|
|
|
7
|
+
|
|
|
8
|
+Base URLs:
|
|
|
9
|
+
|
|
|
10
|
+| Environment/環境 | Base URL | Note/說明 |
|
|
|
11
|
+|---|---|---|
|
|
|
12
|
+| Staging(testable/可測試) | `https://webdev.yico.tw:8088/api` | All examples below use this host/以下範例皆用此位址 |
|
|
|
13
|
+| Production(TBD) | `https://www.example.com/api` | Replace with the production domain at launch/上線後替換為正式網域 |
|
|
|
14
|
+
|
|
|
15
|
+General rules/通用規則:
|
|
|
16
|
+
|
|
|
17
|
+- All endpoints are `GET` and require no authentication./全部為 `GET`,免認證。
|
|
|
18
|
+- Rate limit: 60 requests/minute (`throttle:api`)./節流:每分鐘 60 次。
|
|
|
19
|
+- `Access-Control-Allow-Origin: *` is returned./回傳 CORS 全域允許標頭。
|
|
|
20
|
+- All responses are JSON. Non-ASCII text is `\uXXXX`-escaped; decode before display./回應皆 JSON,非 ASCII 以 `\uXXXX` 跳脫,顯示前請解碼。
|
|
|
21
|
+- `{locale}` path parameter: `tw` (Traditional Chinese/繁中) or `en` (English/英文). Any other value returns 404./語系路徑參數僅 `tw`/`en`,其餘 404。
|
|
|
22
|
+- Long strings in examples are trimmed with `...` for readability./範例長字串以 `...` 節錄。
|
|
|
23
|
+- Image fields use snake_case: `img_pc` / `img_mobile` (renamed 2026-10-21; the old `imgPC` / `imgMobile` keys are no longer returned)./圖片欄位為 snake_case,舊欄位名稱已不再回傳。
|
|
|
24
|
+
|
|
|
25
|
+Endpoints/端點一覽:
|
|
|
26
|
+
|
|
|
27
|
+| Method | Path/路徑 | Description/說明 |
|
|
|
28
|
+|---|---|---|
|
|
|
29
|
+| GET | `/api/{locale}/news` | Featured (top) article, year filter list, SEO meta/置頂文章、年份清單、SEO |
|
|
|
30
|
+| GET | `/api/{locale}/news/list` | Article list with pagination and year/month filter/文章列表(分頁、年月篩選) |
|
|
|
31
|
+| GET | `/api/{locale}/news/detail/{id}` | Article body, paragraphs, prev/next links/文章內文、段落、前後篇 |
|
|
|
32
|
+| GET | `/api/{locale}/esg` | ESG hero section and tab list/ESG 主視覺與頁籤 |
|
|
|
33
|
+| GET | `/api/{locale}/esg/{key}` | Single ESG page by tab key/單一 ESG 頁面 |
|
|
|
34
|
+
|
|
|
35
|
+## 2. Featured article/置頂文章 `GET /api/{locale}/news`
|
|
|
36
|
+
|
|
|
37
|
+No query parameters./無 query 參數。
|
|
|
38
|
+
|
|
|
39
|
+Response `200` (`{data: {meta, yearList, top}}`). If no featured article exists, the body is `[]` (empty array, not an object) — handle both shapes./成功回 `{data:{...}}`;若無置頂資料回 `[]`(空陣列非物件),請相容兩種形狀。
|
|
|
40
|
+
|
|
|
41
|
+- `yearList`: months that contain articles, format `YYYY/MM`, descending./有文章的年月,`YYYY/MM` 倒序。
|
|
|
42
|
+- `top.postDate` format: `Y/m/d`./日期格式 `Y/m/d`。
|
|
|
43
|
+
|
|
|
44
|
+```json
|
|
|
45
|
+{
|
|
|
46
|
+ "data": {
|
|
|
47
|
+ "meta": {
|
|
|
48
|
+ "meta_title": "秦嘉鴻回憶錄全新出版",
|
|
|
49
|
+ "meta_keyword": "秦嘉鴻 回憶錄 油品大亨 ...",
|
|
|
50
|
+ "meta_description": "透過秦嘉鴻董事長的回憶錄,得以領略為人處...",
|
|
|
51
|
+ "img_pc": null
|
|
|
52
|
+ },
|
|
|
53
|
+ "yearList": ["2026/07", "2026/01", "2025/04"],
|
|
|
54
|
+ "top": {
|
|
|
55
|
+ "id": 49,
|
|
|
56
|
+ "categoryId": 1,
|
|
|
57
|
+ "category": "最新公告",
|
|
|
58
|
+ "postDate": "2025/04/24",
|
|
|
59
|
+ "title": "益州董事長秦嘉鴻 出版回憶錄",
|
|
|
60
|
+ "img_pc": "https://webdev.yico.tw:8088//storage/news/01KJ9JW5GAC910DRBH2ZZPEKVG.webp",
|
|
|
61
|
+ "img_mobile": "https://webdev.yico.tw:8088//storage/news/01KJ9GRA0EBP8NPE3BH1ZWY.webp",
|
|
|
62
|
+ "written": "黃全興",
|
|
|
63
|
+ "description": "益州集團董事長、前國策顧問、前中華民國工業區廠商聯合總會理事..."
|
|
|
64
|
+ }
|
|
|
65
|
+ }
|
|
|
66
|
+}
|
|
|
67
|
+```
|
|
|
68
|
+
|
|
|
69
|
+## 3. Article list/文章列表 `GET /api/{locale}/news/list`
|
|
|
70
|
+
|
|
|
71
|
+Query parameters/參數:
|
|
|
72
|
+
|
|
|
73
|
+| Name/名稱 | Type/型別 | Default/預設 | Description/說明 |
|
|
|
74
|
+|---|---|---|---|
|
|
|
75
|
+| `page` | integer | 1 | Page number/頁碼 |
|
|
|
76
|
+| `per_page` | integer | 15 | Items per page; `-1` returns all without pagination/每頁筆數;`-1` 取全部不分頁 |
|
|
|
77
|
+| `year` | integer | — | Filter by year/按年篩選 |
|
|
|
78
|
+| `month` | integer | — | Must be used together with `year` (month-only is ignored)/需與 `year` 並用,單獨傳入無效 |
|
|
|
79
|
+
|
|
|
80
|
+Filtering and ordering/過濾與排序:only visible articles within their publish window (`start_date`/`end_date`); ordered by `order` DESC then `post_date` DESC./僅回可見且在有效期內的文章;依 `order` 倒序再依發佈日倒序。
|
|
|
81
|
+
|
|
|
82
|
+Response `200 {"data": {"pagination": {...}, "list": [...]}}`./成功回此形狀。
|
|
|
83
|
+
|
|
|
84
|
+- `pagination.page` and `per_page` are returned as **strings**./`page`/`per_page` 回傳為**字串**。
|
|
|
85
|
+- Empty result: `total: 0`, `total_page: 1` (not 0), `list: []`./空結果時 `total_page` 為 1。
|
|
|
86
|
+- List item `postDate` format: `Y.m.d` (note: different from §2/§4 which use `Y/m/d`)./此端日期為 `Y.m.d`(與 §2/§4 的 `Y/m/d` 不同)。
|
|
|
87
|
+
|
|
|
88
|
+```json
|
|
|
89
|
+{
|
|
|
90
|
+ "data": {
|
|
|
91
|
+ "pagination": { "page": 1, "per_page": "2", "total": 32, "total_page": 16 },
|
|
|
92
|
+ "list": [
|
|
|
93
|
+ {
|
|
|
94
|
+ "id": 2,
|
|
|
95
|
+ "categoryId": 1,
|
|
|
96
|
+ "category": "最新公告",
|
|
|
97
|
+ "postDate": "2015.05.06",
|
|
|
98
|
+ "title": "秦嘉鴻:要4贏,不要4輸",
|
|
|
99
|
+ "img_pc": "https://webdev.yico.tw:8088//storage/news/01KJ9JE6JS0HMAF4XMWQ7X67SB.jpg",
|
|
|
100
|
+ "img_mobile": "https://webdev.yico.tw:8088//storage/news/01KJ9JE6KWVA0V1WY9HMZ3T9SJ.jpg",
|
|
|
101
|
+ "written": "記者黃全興/中時電子報",
|
|
|
102
|
+ "description": "5月1日立法院院會3讀通過「加薪四法」中的《公司法》修正案,..."
|
|
|
103
|
+ }
|
|
|
104
|
+ ]
|
|
|
105
|
+ }
|
|
|
106
|
+}
|
|
|
107
|
+```
|
|
|
108
|
+
|
|
|
109
|
+## 4. Article detail/文章內文 `GET /api/{locale}/news/detail/{id}`
|
|
|
110
|
+
|
|
|
111
|
+- `{id}`: numeric article ID (non-numeric → 404)./數字 ID(非數字 404)。
|
|
|
112
|
+- `?preview=1`: returns the article even if hidden or outside its publish window (for draft preview)./`?preview=1` 可讀取隱藏/未上架文章(草稿預覽用)。
|
|
|
113
|
+- Success `200 {"data": {...}}`; missing or unpublished → `404 {"message": "news not found"}`./成功 200;不存在或未上架 404。
|
|
|
114
|
+- `paragraphs` are ordered; types: `text` (`content` is HTML), `image` (`images: [{img_url, alt}]`), `video` (`video_img_url`, `is_yt`, `video_url`, `content` as caption)./段落依序排列,型別如列。
|
|
|
115
|
+- `otherNews.previous` = newer article, `next` = older article; absent when none./前後篇缺則無該鍵。
|
|
|
116
|
+
|
|
|
117
|
+```json
|
|
|
118
|
+{
|
|
|
119
|
+ "data": {
|
|
|
120
|
+ "categoryId": 1,
|
|
|
121
|
+ "category": "最新公告",
|
|
|
122
|
+ "postDate": "2015/05/06",
|
|
|
123
|
+ "title": "秦嘉鴻:要4贏,不要4輸",
|
|
|
124
|
+ "description": "5月1日立法院院會3讀通過「加薪四法」中的《公司法》修正案,...",
|
|
|
125
|
+ "written": "記者黃全興/中時電子報",
|
|
|
126
|
+ "img_pc": "https://webdev.yico.tw:8088//storage/news/01KJ9JE6JS0HMAF4XMWQ7X67SB.jpg",
|
|
|
127
|
+ "img_mobile": "https://webdev.yico.tw:8088//storage/news/01KJ9JE6KWVA0V1WY9HMZ3T9SJ.jpg",
|
|
|
128
|
+ "metaTitle": "測試SEO",
|
|
|
129
|
+ "metaKeyword": "",
|
|
|
130
|
+ "metaDesc": "",
|
|
|
131
|
+ "metaImg": null,
|
|
|
132
|
+ "paragraphs": [
|
|
|
133
|
+ { "type": "text", "content": "<h4 class=\"lexical__h4\" dir=\"ltr\"><span ...>5月1日...</span></h4>" },
|
|
|
134
|
+ { "type": "image", "images": [{ "img_url": "https://webdev.yico.tw:8088//storage/news/extraPhoto/01KJ9BK7695DZX6QRDNVSW2FFN.jpg", "alt": "中華民國工業區廠商聯合總會理事長秦嘉鴻。圖/黃全興" }] }
|
|
|
135
|
+ ],
|
|
|
136
|
+ "otherNews": {
|
|
|
137
|
+ "next": { "id": 30, "categoryId": 1, "category": "最新公告", "postDate": "2022/07/27", "title": "國策顧問捐贈台大醫院雲林分院N95口罩用行動力挺醫護", "...": "..." }
|
|
|
138
|
+ }
|
|
|
139
|
+ }
|
|
|
140
|
+}
|
|
|
141
|
+```
|
|
|
142
|
+
|
|
|
143
|
+## 5. ESG hero/ESG 主視覺 `GET /api/{locale}/esg`
|
|
|
144
|
+
|
|
|
145
|
+Response `200 {"data": {"meta": {...}, "img_pc", "img_mobile", "title", "description", "tab_list": [{text, key}]}}`. The `tab_list` key is absent when no ESG pages exist./成功回此形狀;無 ESG 資料時缺 `tab_list` 鍵。
|
|
|
146
|
+
|
|
|
147
|
+```json
|
|
|
148
|
+{
|
|
|
149
|
+ "data": {
|
|
|
150
|
+ "meta": { "meta_title": "", "meta_keyword": "", "meta_description": "", "og_img": null },
|
|
|
151
|
+ "img_pc": null,
|
|
|
152
|
+ "img_mobile": null,
|
|
|
153
|
+ "title": "經營者的話",
|
|
|
154
|
+ "description": "面對全球經濟變動與氣候挑戰,企業責任不僅在於追求經濟成長,更...",
|
|
|
155
|
+ "tab_list": [
|
|
|
156
|
+ { "text": "永續經營", "key": "永續經營" },
|
|
|
157
|
+ { "text": "公司治理", "key": "公司治理" },
|
|
|
158
|
+ { "text": "創新研發", "key": "創新研發" },
|
|
|
159
|
+ { "text": "綠色承諾", "key": "綠色承諾" },
|
|
|
160
|
+ { "text": "社會共融", "key": "社會共融" }
|
|
|
161
|
+ ]
|
|
|
162
|
+ }
|
|
|
163
|
+}
|
|
|
164
|
+```
|
|
|
165
|
+
|
|
|
166
|
+## 6. ESG page/ESG 單頁 `GET /api/{locale}/esg/{key}`
|
|
|
167
|
+
|
|
|
168
|
+- `{key}` is the tab `keyword` (URL-encode non-ASCII, e.g. `%E6%B0%B8%E7%BA%8C%E7%B6%93%E7%87%9F`)./`{key}` 為頁籤 keyword,非 ASCII 請 URL 編碼。
|
|
|
169
|
+- Success `200 {"data": {"banner": {...}, "paragraphs": [...]}}`./成功回此形狀。
|
|
|
170
|
+- **Miss returns HTTP 200 (not 404)** with `{"status": "fail", "message": "查無資料"}` — clients MUST check the `status` field, not only the HTTP code./**查無資料時仍回 HTTP 200**,body 為上式——請務必判斷 `status` 欄,不可只看 HTTP 碼。
|
|
|
171
|
+
|
|
|
172
|
+```json
|
|
|
173
|
+{
|
|
|
174
|
+ "data": {
|
|
|
175
|
+ "banner": {
|
|
|
176
|
+ "img_pc": "https://webdev.yico.tw:8088//storage/esg/01KKE6AH4Q989Z7AQ4AMVDTSR8.jpg",
|
|
|
177
|
+ "img_mobile": "https://webdev.yico.tw:8088//storage/esg/01KKE6AH53W3HWH61CXXBKNFZD.jpg",
|
|
|
178
|
+ "img_alt": "永續經營",
|
|
|
179
|
+ "text": "邁向百年企業的根基..."
|
|
|
180
|
+ },
|
|
|
181
|
+ "paragraphs": [
|
|
|
182
|
+ { "type": "text", "content": "永續經營一、永續治理組織為傳承企業經營理念並確立長達發展方針..." },
|
|
|
183
|
+ { "type": "grid", "columns": 2, "content": [{ "type": "text", "content": "家族理事會家族最高治理單位..." }] },
|
|
|
184
|
+ { "type": "table", "is_card": false,
|
|
|
185
|
+ "header": [{ "align": 1, "text": "公(協)會組織" }, { "align": 1, "text": "參與資格 " }],
|
|
|
186
|
+ "body": [[{ "align": 1, "text": "<p...>..." }, { "align": 1, "text": "<p...>..." }]] }
|
|
|
187
|
+ ]
|
|
|
188
|
+ }
|
|
|
189
|
+}
|
|
|
190
|
+```
|
|
|
191
|
+
|
|
|
192
|
+Paragraph types/段落型別:`text` (`content`, HTML) · `grid` (`columns`, `content[]` of text blocks/文字塊陣列) · `table` (`is_card`, `header[{align, text}]`, `body` 2-D array/二維陣列) · `image` (`images[{image_url, alt}]`) · `video` (`is_yt: true`, `video_img_url`, `video_url`, `content`). Cell `align` is a numeric code; cell text may contain HTML./`align` 為數字碼,cell 文字可含 HTML。
|
|
|
193
|
+
|
|
|
194
|
+Miss example/查無範例(HTTP 200):
|
|
|
195
|
+
|
|
|
196
|
+```json
|
|
|
197
|
+{ "status": "fail", "message": "查無資料" }
|
|
|
198
|
+```
|
|
|
199
|
+
|
|
|
200
|
+```js
|
|
|
201
|
+// Recommended client check/建議判斷方式
|
|
|
202
|
+const res = await fetch(url).then(r => r.json());
|
|
|
203
|
+if (res.status === 'fail') { /* no such page/無此頁面 */ }
|
|
|
204
|
+```
|
|
|
205
|
+
|
|
|
206
|
+## 7. Data models/資料模型
|
|
|
207
|
+
|
|
|
208
|
+Common article fields/通用文章欄位:
|
|
|
209
|
+
|
|
|
210
|
+| Field/欄位 | Type/型別 | Description/說明 |
|
|
|
211
|
+|---|---|---|
|
|
|
212
|
+| `id` | integer | Article ID/文章 ID |
|
|
|
213
|
+| `categoryId` | integer | Category ID/分類 ID |
|
|
|
214
|
+| `category` | string | Localized category name/在地化分類名 |
|
|
|
215
|
+| `postDate` | string | `Y.m.d` in list (§3), `Y/m/d` elsewhere/列表 `Y.m.d`,其餘 `Y/m/d` |
|
|
|
216
|
+| `title` | string | Localized title/在地化標題 |
|
|
|
217
|
+| `description` | string | Localized summary/在地化摘要 |
|
|
|
218
|
+| `written` | string | Author/byline/作者 |
|
|
|
219
|
+| `img_pc` / `img_mobile` | string|null | Desktop/mobile image URLs (may contain `//`)/桌機/手機圖(或有雙斜線) |
|
|
|
220
|
+| `metaTitle` / `metaKeyword` / `metaDesc` / `metaImg` | string|null | SEO fields, detail only/SEO 欄位,僅內文 |
|
|
|
221
|
+
|
|
|
222
|
+## 8. Error handling/錯誤處理
|
|
|
223
|
+
|
|
|
224
|
+| HTTP | Body | When/時機 |
|
|
|
225
|
+|---|---|---|
|
|
|
226
|
+| 200 | `{"status": "fail", "message": "查無資料"}` | ESG key not found (see §6)/ESG 查無資料 |
|
|
|
227
|
+| 404 | `{"message": "news not found"}` | Article missing or unpublished/文章不存在或未上架 |
|
|
|
228
|
+| 404 | HTML error page | Unknown path, non-`tw`/`en` locale, or non-numeric detail id/未知路徑、非 `tw`/`en` 語系、非數字 id |
|
|
|
229
|
+| 429 | JSON | Over 60 requests/minute/超過節流 |
|