常見問題

JSON:API 的版本號代表什麼意義？

JSON:API 已達到穩定版本 1.0，它將永遠保持向下相容，採用「只新增，不移除」的策略。

維護版本號是為了

有幾個原因

HAL 遞迴地嵌入子文件，而 JSON:API 則將整個物件圖形扁平化到頂層。這表示如果相同的「人員」被不同類型的物件（例如，文章和評論的作者）引用，此格式可確保在有效負載中每個人員文件只有一個表示形式。
同樣地，JSON:API 使用 ID 進行連結，這使得可以快取複合回應中的文件，然後將後續請求限制為僅請求本地尚未存在的文件。如果幸運的話，這甚至可以完全消除 HTTP 請求。
HAL 是一種序列化格式，但沒有說明如何更新文件。JSON:API 考慮了如何更新現有記錄（依賴 PATCH 和 JSON Patch），以及這些更新如何與從 GET 請求返回的複合文件交互。它還描述了如何建立和刪除文件，以及這些更新的 200 和 204 回應的含義。

簡而言之，JSON:API 嘗試將使用 JSON 作為交換格式的類似臨時客戶端-伺服器介面正式化。它特別關注於將這些 API 與知道如何快取已看到的文件並避免再次請求它們的智慧型客戶端一起使用。

它提取自已被許多專案使用的真實世界程式庫，這為請求/回應方面（HAL 中沒有）和交換格式本身提供了資訊。

每當客戶端請求 URI 時，伺服器可以在其回應中包含 Allow 標頭，以指示請求的資源支援的方法。希望支援方法發現的伺服器應包含此標頭。然後，客戶端可以向 URI 發送 HEAD 請求（或任何其他類型的請求），以發現其支援的方法。

例如，客戶端可能會請求 HEAD /articles，並且回應可能包含標頭 Allow: GET,POST，表示客戶端可以 GET 集合，也可以 POST 到集合以建立新資源。

JSON:API 仍在研究一種方法，讓資源可以宣傳和詳細說明它們支援的非標準操作。歡迎加入討論！

HTTP 規格不允許使用 PUT 來部分更新資源（即僅更改其部分狀態）。相反，PUT 應該完全替換資源的狀態

「PUT 方法請求使用請求訊息有效負載中的狀態…建立或替換目標資源的狀態。成功 PUT 特定表示形式表示後續對同一目標資源的 GET 將導致發送等效的表示形式…」

因此，部分更新的正確方法是 PATCH，這也是 JSON:API 使用的方法。由於 PATCH 也可以合規地用於完全資源替換，因此 JSON:API 目前不需要為 PUT 定義任何行為。但是，它將來可能會定義 PUT 語義。

過去，許多 API 使用 PUT 進行部分更新，因為 PATCH 尚未得到很好的支援。但是，現在幾乎所有客戶端都支援 PATCH，而那些不支援的客戶端可以輕鬆地解決。

有的，您可以在 https://jsonapi.dev.org.tw/schema 找到 JSON Schema 定義。此模式的限制性盡可能強，但在您的文件中具有擴展的彈性。驗證不會產生偽陰性，但為了靈活性可能會產生偽陽性。

您可以在 https://json-schema.dev.org.tw 找到有關 JSON Schema 格式的更多資訊。

JSON 陣列是自然排序的，而集合需要中繼資料來指定成員之間的順序。因此，陣列允許根據預設或指定的標準進行更自然的排序。

主要資源應該隔離，因為它們的順序和數量通常很重要。必須以類型以外的方式區分主要資源和相關資源，因為主要資源可能具有相同類型的相關資源（例如，「人員」的「父母」）。將相關資源嵌套在 included 中可以防止這種可能的衝突。

JSON:API 對 URI 結構沒有任何要求，實作可以自由使用任何形式。