首先，請務必記住 API 設計和使用的一個重要法則 Postel's Law(又稱作穩健性原則):

• Be liberal in what you accept, be conservative in what you send

下面是關于 API 設計的一些基本問題

API First

將 API 視作產品，并向產品開發一樣設計和維護 API

在代碼實現前的 Design 階段，就優先定義符合標準規范的 API

與客戶(API 的使用者)一起設計和審查 API

設計可用性、可讀性和可維護性的 API

長期積極維護 API 并保持 API 的一致性

代碼結構

項目(Git Repo) 中應包含以下目錄用于描述 API

• README.MD
  • 可以包含服務 API Spec 的 Jira Link
• 文檔
  • 在 doc/* 目錄下的 markdown 文件或鏈接到 git
• 接口定義
  • 按 API 版本分目錄 v[0-9]*/*
  • 每個版本中需包含 swagger yaml 文件

安全

無論是 public API 還是 internal API，在設計時都需要考慮安全性問題。對于外部 API，暴露在因特網上本來就充滿了風險。對于內部 API，不要認為內網是安全的，比如在微服務網絡中，要避免級聯失敗或者第三方繼承點問題。可以采用以下方案提高 API 的可用性：

• 總是使用 SSL(Public API 必須開啟，內部 API 根據具體場景具體分析)
• Public API 必須支持 CSRF
  • Is your Web API susceptible to a CSRF exploit?
• Throttling
  • 主要針對 public API， 此外 internal API 也需要考慮承載能力
  • 響應 503 with Retry-After header
• 考慮 Subtle Denial of Service
  • DoS attacks：Slowloris, Billion laughs, and ReDoS
• Authentication
  • 針對 Public API 使用 Oauth2 或者 HTTP Basic Authentication
  • 針對內部 API 可以使用協商的加密認證算法

命名規范

總是使用小駝峰

使用美式英語

允許使用縮寫

產品名

API

config (configuration)

id (identifier)

spec (specification)

stats (statistics)

使用準確描述 API 的命名，而非籠統模糊的命名(如 items)

盡量避免使用編程語言中的保留字

文檔

遵循 OpenAPI Spec version 3，使用 swagger-editor 編輯文檔，每個 API 的描述至少包含以下內容：

• x-api-id: 為每個 API 設置 UUID 以便于索引
• x-audience：API 受眾
  • internal-component
  • internal-company
  • external-public
• title: API 名稱
• version：API 版本
• description：API 描述
• contact/{name,url,email}：維護團隊
• 使用美式英語書寫

使用 JSON 作為數據交換格式

默認采用 JSON 數據類型，非 JSON 媒體類型請使用其他相應的媒體類型

JSON 應符合 RFC4627 和 RFC 7159，并滿足以下的要求：

針對 PUT/PATCH/POST request body 以及任意響應的 response body 使用標準媒體類型 application/json

響應和請求中優先使用以下預定義的標準字段

createdAt

updatedAt

deletedAt

使用 UTF-8 編碼

布爾值和數組不能使用 null

使用UTC（世界標準時間）時間，用ISO8601進行格式化YYYY-MM-DDTHH:MM:SSZ

API 中的 date/time 應該包含 timezone 信息 RFC3339

盡可能為資源提供默認的創建時間 created_at 和更新時間 updated_at

統一格式的國家，語言和錢幣

ISO 3166-1-alpha2 country codes

ISO 639-1 language code 或者 BCP 47

ISO 4217 currency codes

來自公眾號 無人深空，一個專注于技術和扯淡的公眾號，請不要關注

總結

以上是生活随笔為你收集整理的api数据加密的定义_API 设计基础规范的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。