這是一套很好的開發Restful API的指南。由Zalando提供。
Zalando 的軟體架構以解耦微服務為中心，透過帶有 JSON 負載的 RESTful API 提供功能。小型工程團隊在其 AWS（團隊）賬戶中擁有、部署和運營這些微服務。我們的 API 最純粹地表達了我們系統的功能，因此是非常有價值的業務資產。自從我們開始制定新的開放平臺戰略以來，設計高質量、持久的 API 對我們來說變得更加重要，該戰略將 Zalando 從一家線上商店轉變為一個廣闊的時尚平臺。我們的戰略強調開發大量公共 API 供外部業務合作伙伴透過第三方應用程式使用。
考慮到這一點，我們採用“API 優先”作為我們的關鍵工程原則之一。微服務開發從程式碼外部的 API 定義開始，理想情況下涉及充足的同行評審反饋以實現高質量的 API。 API First 包含一套與質量相關的標準，並培育同行評審文化，包括輕量級評審程式。我們鼓勵我們的團隊遵循它們，以確保我們的 API：
- 易於理解和學習
- 是通用的，是從特定的實現和用例中抽象出來的
- 堅固且易於使用
- 具有共同的外觀和感覺
- 遵循一致的 RESTful 風格和語法
- 與其他團隊的 API 和我們的全球架構保持一致
理想情況下，所有 Zalando API 看起來都像是由同一位作者建立的。
本指南中使用的約定
本節中使用的要求級別關鍵字“必須”、“不得”、“必需”、“應”、“不應”、“應該”、“不應該”、“推薦”、“可以”和“可選”文件（不區分大小寫）應按照RFC 2119中的描述進行解釋。
目錄
- 一、簡介
- 本指南中使用的約定
- Zalando具體資訊
- API設計原則
- API 作為產品
- API優先
- 必須遵循API優先原則
- 必須使用 OpenAPI 提供 API 規範
- 應提供API使用手冊
- 必須使用美式英語編寫 API
- 必須僅使用持久且不可變的遠端引用
- 必須包含 API 元資訊
- 必須使用語義版本控制
- 必須提供 API 識別符號
- 必須提供 API 受眾
- 必須/應該/可以使用功能命名模式
- 必須遵循主機名的命名約定
- 必須保護端點
- 必須定義和分配許可權（範圍）
- 必須遵循許可權（範圍）的命名約定
- 必須使用標準資料格式
- 必須定義數字和整數型別的格式
- 必須使用日期和時間屬性的標準格式
- 應選擇日期或日期時間格式中適當的一種
- 應使用持續時間和間隔屬性的標準格式
- 必須使用國家、語言和貨幣屬性的標準格式
- 如果客戶端可以從不同的資源表示中進行選擇，則應該使用內容協商
- 只應在必要時使用 UUID
- 不應使用 /api 作為基本路徑
- 資源名稱必須採用複數形式
- 必須使用 URL 友好的資源識別符號
- 路徑段必須使用短橫線大小寫
- 必須使用沒有空路徑段和尾部斜槓的規範化路徑
- 必須保持 URL 不含動詞
- 必須避免採取行動——考慮資源
- 應該定義有用的資源
- 必須使用特定於域的資源名稱
- 應該對完整的業務流程進行建模
- 必須透過路徑段識別資源和子資源
- 可以將複合鍵公開為資源識別符號
- 可以考慮使用（非）巢狀 URL
- 應限制資源型別的數量
- 應限制子資源級別的數量
- 查詢引數必須使用蛇形命名法（不能使用駝峰命名法）
- 必須堅持傳統的查詢引數
- 必須使用 JSON 作為有效負載資料交換格式
- 應該設計用於讀寫的單一資源模式
- 應注意不完全支援 JSON/unicode 的服務
- 可以使用資料特定標準格式傳遞非 JSON 媒體型別
- 應使用標準媒體型別
- 應該使用複數陣列名稱
- 必須屬性名稱必須是蛇形命名法（並且不能是駝峰命名法）
- 應使用 UPPER_SNAKE_CASE 字串宣告列舉值
- 應使用_at字尾命名日期/時間屬性
- 應該使用定義地圖additionalProperties
- 必須null對不存在的屬性使用相同的語義
- 不得用於null布林屬性
- 不應該用於null空陣列
- 必須使用通用欄位名稱和語義
- 必須使用公共地址欄位
- 必須使用共同貨幣物件
- 必須正確使用 HTTP 方法
- 必須滿足通用方法屬性
- 應該考慮設計POST和PATCH冪等
- 應使用輔助金鑰進行冪等POST設計
- 可以支援非同步請求處理
- 必須定義標頭和查詢引數的集合格式
- 應該使用查詢引數設計簡單的查詢語言
- 應該使用 JSON 設計複雜的查詢語言
- 必須記錄隱式響應過濾
- 必須使用官方 HTTP 狀態程式碼
- 必須指定成功和錯誤響應
- 應僅使用最常見的 HTTP 狀態程式碼
- 必須使用最具體的 HTTP 狀態程式碼
- 批次請求必須使用程式碼 207
- 必須使用帶有標頭的程式碼 429 進行速率限制
- 必須支援問題 JSON
- 不得暴露堆疊跟蹤
- 不應使用重定向程式碼
- 使用標準標頭定義
- 可以使用標準標頭
- 應該使用 kebab-case 和大寫的單獨單詞作為 HTTP 標頭
- 必須Content-*正確使用
- 應該使用Locationheader 而不是Content-Locationheader
- 可以使用Content-Location標頭
- 可以考慮支援Prefer標頭來處理處理首選項
- 可以ETag考慮與If-Match/If-None-Matchheader支援
- 可以考慮支援Idempotency-Key標頭
- 應僅使用指定的專有 Zalando 標頭
- 必須傳播專有標頭
- 必須支援X-Flow-ID
- 必須使用 REST 成熟度級別 2
- 可以使用 REST 成熟度級別 3 - HATEOAS
- 必須使用通用的超文字控制元件
- 應使用簡單的超文字控制元件進行分頁和自引用
- 必須使用完整、絕對的 URI 進行資源標識
- 不得將連結標頭與 JSON 實體一起使用
- 應減少頻寬需求並提高響應能力
- 應該使用gzip壓縮
- 應透過過濾支援部分響應
- 應允許可選地嵌入子資源
- 必須記錄可快取GET、HEAD和POST端點
- 必須支援分頁
- 應首選基於遊標的分頁，避免基於偏移量的分頁
- 應使用分頁響應頁面物件
- 應使用分頁連結
- 應避免總結果計數
- 不得破壞向後相容性
- 應該更喜歡相容的擴充套件
- 應該保守地設計 API
- 必須讓客戶端做好接受相容 API 擴充套件的準備
- 預設情況下，必須將 OpenAPI 規範視為開放擴充套件
- 應避免版本控制
- 必須使用媒體型別版本控制
- 不得使用 URL 版本控制
- 必須始終返回 JSON 物件作為頂級資料結構
- 應該使用開放式值列表 (x-extensible-enum) 進行列舉
- 必須反映 API 規範中的棄用
- API 關閉之前必須獲得客戶的批准
- 必須就棄用時間跨度收集外部合作伙伴的同意
- 必須監控計劃在日落時棄用的 API 的使用情況
- 應在響應中新增Deprecation標Sunset
- 應Deprecation新增對和Sunsetheader 的監控
- 不得開始使用已棄用的 API
- 必須釋出 OpenAPI 規範
- 應監控 API 使用情況
- 必須定義符合整體 API 指南的事件
- 必須將事件視為服務介面的一部分
- 必須使事件模式可供審查
- 必須指定事件並將其註冊為事件型別
- 必須遵循事件型別名稱的命名約定
- 必須表明事件型別的所有權
- 必須仔細定義相容模式
- 必須確保事件模式符合 OpenAPI 模式物件
- 應避免additionalProperties在事件型別模式中
- 必須使用事件型別模式的語義版本控制
- 必須確保事件符合事件類別
- 必須提供強制性事件後設資料
- 必須提供唯一的事件識別符號
- 必須使用一般事件來指示業務流程中的步驟
- 應為一般事件提供明確的事件排序
- 必須使用資料更改事件來發出突變訊號
- 必須為資料更改事件提供顯式事件排序
- 應該對資料更改事件使用雜湊分割槽策略
- 應避免將敏感資料寫入事件
- 消費事件時必須能夠防止重複
- 應該設計冪等亂序處理
- 必須確保事件定義有用的業務資源
- 應確保資料更改事件與 API 資源匹配
- 必須保持事件的向後相容性