# Yico Website API Specification/前台 API 規格說明 Version/版本:1.1(Verified against staging/已對 staging 實測驗證:2026-10-13;2026-10-21 圖片欄位改名) Machine-readable format/機器格式:see `openapi.yaml` in the same directory/同目錄 `openapi.yaml` ## 1. Overview/總覽 Base URLs: | Environment/環境 | Base URL | Note/說明 | |---|---|---| | Staging(testable/可測試) | `https://webdev.yico.tw:8088/api` | All examples below use this host/以下範例皆用此位址 | | Production(TBD) | `https://www.example.com/api` | Replace with the production domain at launch/上線後替換為正式網域 | General rules/通用規則: - All endpoints are `GET` and require no authentication./全部為 `GET`,免認證。 - Rate limit: 60 requests/minute (`throttle:api`)./節流:每分鐘 60 次。 - `Access-Control-Allow-Origin: *` is returned./回傳 CORS 全域允許標頭。 - All responses are JSON. Non-ASCII text is `\uXXXX`-escaped; decode before display./回應皆 JSON,非 ASCII 以 `\uXXXX` 跳脫,顯示前請解碼。 - `{locale}` path parameter: `tw` (Traditional Chinese/繁中) or `en` (English/英文). Any other value returns 404./語系路徑參數僅 `tw`/`en`,其餘 404。 - Long strings in examples are trimmed with `...` for readability./範例長字串以 `...` 節錄。 - Image fields use snake_case: `img_pc` / `img_mobile` (renamed 2026-10-21; the old `imgPC` / `imgMobile` keys are no longer returned)./圖片欄位為 snake_case,舊欄位名稱已不再回傳。 Endpoints/端點一覽: | Method | Path/路徑 | Description/說明 | |---|---|---| | GET | `/api/{locale}/news` | Featured (top) article, year filter list, SEO meta/置頂文章、年份清單、SEO | | GET | `/api/{locale}/news/list` | Article list with pagination and year/month filter/文章列表(分頁、年月篩選) | | GET | `/api/{locale}/news/detail/{id}` | Article body, paragraphs, prev/next links/文章內文、段落、前後篇 | | GET | `/api/{locale}/esg` | ESG hero section and tab list/ESG 主視覺與頁籤 | | GET | `/api/{locale}/esg/{key}` | Single ESG page by tab key/單一 ESG 頁面 | ## 2. Featured article/置頂文章 `GET /api/{locale}/news` No query parameters./無 query 參數。 Response `200` (`{data: {meta, yearList, top}}`). If no featured article exists, the body is `[]` (empty array, not an object) — handle both shapes./成功回 `{data:{...}}`;若無置頂資料回 `[]`(空陣列非物件),請相容兩種形狀。 - `yearList`: months that contain articles, format `YYYY/MM`, descending./有文章的年月,`YYYY/MM` 倒序。 - `top.postDate` format: `Y/m/d`./日期格式 `Y/m/d`。 ```json { "data": { "meta": { "meta_title": "秦嘉鴻回憶錄全新出版", "meta_keyword": "秦嘉鴻 回憶錄 油品大亨 ...", "meta_description": "透過秦嘉鴻董事長的回憶錄,得以領略為人處...", "img_pc": null }, "yearList": ["2026/07", "2026/01", "2025/04"], "top": { "id": 49, "categoryId": 1, "category": "最新公告", "postDate": "2025/04/24", "title": "益州董事長秦嘉鴻 出版回憶錄", "img_pc": "https://webdev.yico.tw:8088//storage/news/01KJ9JW5GAC910DRBH2ZZPEKVG.webp", "img_mobile": "https://webdev.yico.tw:8088//storage/news/01KJ9GRA0EBP8NPE3BH1ZWY.webp", "written": "黃全興", "description": "益州集團董事長、前國策顧問、前中華民國工業區廠商聯合總會理事..." } } } ``` ## 3. Article list/文章列表 `GET /api/{locale}/news/list` Query parameters/參數: | Name/名稱 | Type/型別 | Default/預設 | Description/說明 | |---|---|---|---| | `page` | integer | 1 | Page number/頁碼 | | `per_page` | integer | 15 | Items per page; `-1` returns all without pagination/每頁筆數;`-1` 取全部不分頁 | | `year` | integer | — | Filter by year/按年篩選 | | `month` | integer | — | Must be used together with `year` (month-only is ignored)/需與 `year` 並用,單獨傳入無效 | Filtering and ordering/過濾與排序:only visible articles within their publish window (`start_date`/`end_date`); ordered by `order` DESC then `post_date` DESC./僅回可見且在有效期內的文章;依 `order` 倒序再依發佈日倒序。 Response `200 {"data": {"pagination": {...}, "list": [...]}}`./成功回此形狀。 - `pagination.page` and `per_page` are returned as **strings**./`page`/`per_page` 回傳為**字串**。 - Empty result: `total: 0`, `total_page: 1` (not 0), `list: []`./空結果時 `total_page` 為 1。 - 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` 不同)。 ```json { "data": { "pagination": { "page": 1, "per_page": "2", "total": 32, "total_page": 16 }, "list": [ { "id": 2, "categoryId": 1, "category": "最新公告", "postDate": "2015.05.06", "title": "秦嘉鴻:要4贏,不要4輸", "img_pc": "https://webdev.yico.tw:8088//storage/news/01KJ9JE6JS0HMAF4XMWQ7X67SB.jpg", "img_mobile": "https://webdev.yico.tw:8088//storage/news/01KJ9JE6KWVA0V1WY9HMZ3T9SJ.jpg", "written": "記者黃全興/中時電子報", "description": "5月1日立法院院會3讀通過「加薪四法」中的《公司法》修正案,..." } ] } } ``` ## 4. Article detail/文章內文 `GET /api/{locale}/news/detail/{id}` - `{id}`: numeric article ID (non-numeric → 404)./數字 ID(非數字 404)。 - `?preview=1`: returns the article even if hidden or outside its publish window (for draft preview)./`?preview=1` 可讀取隱藏/未上架文章(草稿預覽用)。 - Success `200 {"data": {...}}`; missing or unpublished → `404 {"message": "news not found"}`./成功 200;不存在或未上架 404。 - `paragraphs` are ordered; types: `text` (`content` is HTML), `image` (`images: [{img_url, alt}]`), `video` (`video_img_url`, `is_yt`, `video_url`, `content` as caption)./段落依序排列,型別如列。 - `otherNews.previous` = newer article, `next` = older article; absent when none./前後篇缺則無該鍵。 ```json { "data": { "categoryId": 1, "category": "最新公告", "postDate": "2015/05/06", "title": "秦嘉鴻:要4贏,不要4輸", "description": "5月1日立法院院會3讀通過「加薪四法」中的《公司法》修正案,...", "written": "記者黃全興/中時電子報", "img_pc": "https://webdev.yico.tw:8088//storage/news/01KJ9JE6JS0HMAF4XMWQ7X67SB.jpg", "img_mobile": "https://webdev.yico.tw:8088//storage/news/01KJ9JE6KWVA0V1WY9HMZ3T9SJ.jpg", "metaTitle": "測試SEO", "metaKeyword": "", "metaDesc": "", "metaImg": null, "paragraphs": [ { "type": "text", "content": "