https://tarrragon.github.io/blog/tags/standards/Recent content in Standards on TarragonHugo -- gohugo.iozh-TWTarragon (CC BY 4.0)Fri, 03 Jul 2026 00:00:00 +0000https://tarrragon.github.io/blog/backend/11-api-design/cases/standards-jsonapi-antibikeshedding/Fri, 03 Jul 2026 00:00:00 +0000https://tarrragon.github.io/blog/backend/11-api-design/cases/standards-jsonapi-antibikeshedding/<p>這個案例的核心責任是記錄「跨組織標準想解組織內治理問題」的代表性嘗試。</p> <h2 id="觀察">觀察</h2> <p>官網明言設計目標：「If you&rsquo;ve ever argued with your team about the way your JSON responses should be formatted, JSON:API can help you stop the bikeshedding」。現行版本 1.1（2022-09 定稿、距 1.0 約 7 年）。賣點包含共享慣例帶來的工具重用、以及 client 端可高效快取 response、有時能完全省掉網路請求。</p> <h2 id="判讀">判讀</h2> <p>JSON:API 把價值主張放在組織成本（消除格式爭論）而非技術能力。版本節奏極慢可作兩面判讀：spec 穩定成熟、或演進動能有限。教學上對照 in-house guidelines 路線 —「採現成標準」vs「自建規範加治理機制」是規範治理的核心選擇題。</p> <h2 id="對應大綱">對應大綱</h2> <p>styles/standards/「JSON:API 與 OData 的標準化嘗試」（anchor）、11.10 採標準與自建規範段（已引用）。</p> <h2 id="下一步路由">下一步路由</h2> <p>回 <a href="https://tarrragon.github.io/blog/backend/11-api-design/cases/" data-link-title="模組十一案例庫：API 設計與對外契約" data-link-desc="API 風格流派、版本與相容、介面語意、規範治理的已驗證公開案例集；含反例與覆蓋缺口標明">模組十一案例庫</a>。</p> <h2 id="引用源">引用源</h2> <ul> <li><a href="https://jsonapi.org/">JSON:API 官方網站</a></li> </ul>這個案例的核心責任是記錄「跨組織標準想解組織內治理問題」的代表性嘗試。

觀察

官網明言設計目標：「If you’ve ever argued with your team about the way your JSON responses should be formatted, JSON:API can help you stop the bikeshedding」。現行版本 1.1（2022-09 定稿、距 1.0 約 7 年）。賣點包含共享慣例帶來的工具重用、以及 client 端可高效快取 response、有時能完全省掉網路請求。

判讀

JSON:API 把價值主張放在組織成本（消除格式爭論）而非技術能力。版本節奏極慢可作兩面判讀：spec 穩定成熟、或演進動能有限。教學上對照 in-house guidelines 路線 —「採現成標準」vs「自建規範加治理機制」是規範治理的核心選擇題。

對應大綱

styles/standards/「JSON:API 與 OData 的標準化嘗試」（anchor）、11.10 採標準與自建規範段（已引用）。

下一步路由

回 模組十一案例庫。

引用源

• JSON:API 官方網站

]]>https://tarrragon.github.io/blog/backend/11-api-design/cases/standards-odata-decline/Fri, 03 Jul 2026 00:00:00 +0000https://tarrragon.github.io/blog/backend/11-api-design/cases/standards-odata-decline/<p>這個案例的核心責任是提供跨組織標準化嘗試的退場反例。</p> <h2 id="觀察">觀察</h2> <p>OData v4 是 OASIS 標準且有 ISO/IEC 認證（20802-1/2:2016）、定位是可查詢、可互通的 RESTful API 建構協議、生態工具以 .NET（Restier）與 Java（Apache Olingo）為主。二手分析（Ben Morris、2013）記錄 Netflix 低調關閉 OData catalogue、eBay 同步棄用、歸因三點：生態侷限於 .NET、Microsoft 出身的信任問題、技術面「magic box」批評 — 暴露資料庫內部細節、自動生成 generic 介面而非刻意設計的 API。</p> <h2 id="判讀">判讀</h2> <p>ISO 認證救不了生態萎縮 — marquee adopter 離場的訊號比標準機構背書更能預測標準命運。查詢協議把 repository 直通到 wire 的設計、跟「API 是刻意設計的契約」的治理理念直接衝突 — 這是它進不了 guidelines 主流的深層原因、不只是出身問題。</p> <h2 id="對應大綱">對應大綱</h2> <p>styles/standards/「JSON:API 與 OData 的標準化嘗試」（反例）、11.10 採標準與自建規範段（已引用）。退場分析屬二手來源、標明。</p> <h2 id="下一步路由">下一步路由</h2> <p>回 <a href="https://tarrragon.github.io/blog/backend/11-api-design/cases/" data-link-title="模組十一案例庫：API 設計與對外契約" data-link-desc="API 風格流派、版本與相容、介面語意、規範治理的已驗證公開案例集；含反例與覆蓋缺口標明">模組十一案例庫</a>。</p> <h2 id="引用源">引用源</h2> <ul> <li><a href="https://www.odata.org/">OData 官方網站</a></li> <li><a href="https://www.ben-morris.com/netflix-has-abandoned-odata-does-the-standard-have-a-future-without-an-ecosystem/">Netflix has abandoned OData — does the standard have a future without an ecosystem?（Ben Morris、2013、二手分析）</a></li> </ul>這個案例的核心責任是提供跨組織標準化嘗試的退場反例。

觀察

OData v4 是 OASIS 標準且有 ISO/IEC 認證（20802-1/2:2016）、定位是可查詢、可互通的 RESTful API 建構協議、生態工具以 .NET（Restier）與 Java（Apache Olingo）為主。二手分析（Ben Morris、2013）記錄 Netflix 低調關閉 OData catalogue、eBay 同步棄用、歸因三點：生態侷限於 .NET、Microsoft 出身的信任問題、技術面「magic box」批評 — 暴露資料庫內部細節、自動生成 generic 介面而非刻意設計的 API。

判讀

ISO 認證救不了生態萎縮 — marquee adopter 離場的訊號比標準機構背書更能預測標準命運。查詢協議把 repository 直通到 wire 的設計、跟「API 是刻意設計的契約」的治理理念直接衝突 — 這是它進不了 guidelines 主流的深層原因、不只是出身問題。

對應大綱

styles/standards/「JSON:API 與 OData 的標準化嘗試」（反例）、11.10 採標準與自建規範段（已引用）。退場分析屬二手來源、標明。

下一步路由

回 模組十一案例庫。

引用源

• OData 官方網站
• Netflix has abandoned OData — does the standard have a future without an ecosystem?（Ben Morris、2013、二手分析）

]]>https://tarrragon.github.io/blog/backend/11-api-design/cases/standards-openapi-initiative-evolution/Fri, 03 Jul 2026 00:00:00 +0000https://tarrragon.github.io/blog/backend/11-api-design/cases/standards-openapi-initiative-evolution/<p>這個案例的核心責任是記錄 API 描述標準的成功轉軌路徑、跟 OData（C51）形成直接對照。</p> <h2 id="觀察">觀察</h2> <p>OAI 官網記載 OpenAPI Specification 源自 SmartBear 捐贈的 Swagger Specification；OAI 在 Linux Foundation 下以 open governance 運作、強調 vendor neutrality、治理機構含 Technical Steering Committee 與 Technical Oversight Board、細節公開於 GitHub。範圍已擴展到 OpenAPI 之外：Arazzo（多 API workflow）與 Overlay（API description 自動更新）。</p> <h2 id="判讀">判讀</h2> <p>與 OData 的關鍵差異：轉移時 Swagger 已是事實標準、治理轉移是把既有動能中立化、而非用標準機構背書去創造動能。OAI 站穩後沿「描述 API 的周邊問題」擴張版圖（Arazzo / Overlay）、是標準組織生命週期的可觀察模式。</p> <h2 id="對應大綱">對應大綱</h2> <p>styles/standards/「OpenAPI 與 AsyncAPI 生態」（anchor）、11.10 採標準與自建規範段（已引用）。</p> <h2 id="下一步路由">下一步路由</h2> <p>回 <a href="https://tarrragon.github.io/blog/backend/11-api-design/cases/" data-link-title="模組十一案例庫：API 設計與對外契約" data-link-desc="API 風格流派、版本與相容、介面語意、規範治理的已驗證公開案例集；含反例與覆蓋缺口標明">模組十一案例庫</a>。</p> <h2 id="引用源">引用源</h2> <ul> <li><a href="https://www.openapis.org/about">About the OpenAPI Initiative</a></li> </ul>這個案例的核心責任是記錄 API 描述標準的成功轉軌路徑、跟 OData（C51）形成直接對照。

觀察

OAI 官網記載 OpenAPI Specification 源自 SmartBear 捐贈的 Swagger Specification；OAI 在 Linux Foundation 下以 open governance 運作、強調 vendor neutrality、治理機構含 Technical Steering Committee 與 Technical Oversight Board、細節公開於 GitHub。範圍已擴展到 OpenAPI 之外：Arazzo（多 API workflow）與 Overlay（API description 自動更新）。

判讀

與 OData 的關鍵差異：轉移時 Swagger 已是事實標準、治理轉移是把既有動能中立化、而非用標準機構背書去創造動能。OAI 站穩後沿「描述 API 的周邊問題」擴張版圖（Arazzo / Overlay）、是標準組織生命週期的可觀察模式。

對應大綱

styles/standards/「OpenAPI 與 AsyncAPI 生態」（anchor）、11.10 採標準與自建規範段（已引用）。

下一步路由

回 模組十一案例庫。

引用源

• About the OpenAPI Initiative

]]>https://tarrragon.github.io/blog/backend/11-api-design/cases/standards-asyncapi-complement/Fri, 03 Jul 2026 00:00:00 +0000https://tarrragon.github.io/blog/backend/11-api-design/cases/standards-asyncapi-complement/<p>這個案例的核心責任是記錄「補位式標準化」策略：不另起爐灶、以相容換採用。</p> <h2 id="觀察">觀察</h2> <p>官方文件自述 AsyncAPI 起於 OpenAPI specification 的 adaptation、刻意維持相容並重用 OpenAPI schema；結構差異為 Paths 對 Channels、HTTP verbs 對 Publish / Subscribe、加入 Correlation Id 與 protocol bindings 等 protocol-agnostic 概念；3.0 進一步把 operations 從 channels 拆離。補位論證：「systems don&rsquo;t have just REST APIs or events, but a mix of both」、支援跨同步 / 非同步的 schema 重用與多協議。</p> <h2 id="判讀">判讀</h2> <p>AsyncAPI 明確承認 OpenAPI 的生態位、只填 event-driven 空白 — 以相容性換採用曲線。教學意義：描述格式的邊界即治理邊界 — 組織同時有 REST 加 event 時、規範治理需要兩份 spec 格式但一套 schema 來源。</p> <h2 id="對應大綱">對應大綱</h2> <p>styles/standards/「OpenAPI 與 AsyncAPI 生態」（anchor）、11.10 採標準與自建規範段（已引用）、03 訊息佇列模組交叉。</p> <h2 id="下一步路由">下一步路由</h2> <p>回 <a href="https://tarrragon.github.io/blog/backend/11-api-design/cases/" data-link-title="模組十一案例庫：API 設計與對外契約" data-link-desc="API 風格流派、版本與相容、介面語意、規範治理的已驗證公開案例集；含反例與覆蓋缺口標明">模組十一案例庫</a>。</p> <h2 id="引用源">引用源</h2> <ul> <li><a href="https://www.asyncapi.com/docs/tutorials/getting-started/coming-from-openapi">Coming from OpenAPI（AsyncAPI docs）</a></li> </ul>這個案例的核心責任是記錄「補位式標準化」策略：不另起爐灶、以相容換採用。

觀察

官方文件自述 AsyncAPI 起於 OpenAPI specification 的 adaptation、刻意維持相容並重用 OpenAPI schema；結構差異為 Paths 對 Channels、HTTP verbs 對 Publish / Subscribe、加入 Correlation Id 與 protocol bindings 等 protocol-agnostic 概念；3.0 進一步把 operations 從 channels 拆離。補位論證：「systems don’t have just REST APIs or events, but a mix of both」、支援跨同步 / 非同步的 schema 重用與多協議。

判讀

AsyncAPI 明確承認 OpenAPI 的生態位、只填 event-driven 空白 — 以相容性換採用曲線。教學意義：描述格式的邊界即治理邊界 — 組織同時有 REST 加 event 時、規範治理需要兩份 spec 格式但一套 schema 來源。

對應大綱

styles/standards/「OpenAPI 與 AsyncAPI 生態」（anchor）、11.10 採標準與自建規範段（已引用）、03 訊息佇列模組交叉。

下一步路由

回 模組十一案例庫。

引用源

• Coming from OpenAPI（AsyncAPI docs）

]]>