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

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

下面是關(guān)于 API 設(shè)計的一些基本問題

API First

將 API 視作產(chǎn)品，并向產(chǎn)品開發(fā)一樣設(shè)計和維護 API

在代碼實現(xiàn)前的 Design 階段，就優(yōu)先定義符合標準規(guī)范的 API

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

設(shè)計可用性、可讀性和可維護性的 API

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

代碼結(jié)構(gòu)

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

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

安全

無論是 public API 還是 internal API，在設(shè)計時都需要考慮安全性問題。對于外部 API，暴露在因特網(wǎng)上本來就充滿了風(fēng)險。對于內(nèi)部 API，不要認為內(nèi)網(wǎng)是安全的，比如在微服務(wù)網(wǎng)絡(luò)中，要避免級聯(lián)失敗或者第三方繼承點問題?？梢圆捎靡韵路桨柑岣?API 的可用性：

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

命名規(guī)范

總是使用小駝峰

使用美式英語

允許使用縮寫

產(chǎn)品名

API

config (configuration)

id (identifier)

spec (specification)

stats (statistics)

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

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

文檔

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

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

使用 JSON 作為數(shù)據(jù)交換格式

默認采用 JSON 數(shù)據(jù)類型，非 JSON 媒體類型請使用其他相應(yīng)的媒體類型

JSON 應(yīng)符合 RFC4627 和 RFC 7159，并滿足以下的要求：

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

響應(yīng)和請求中優(yōu)先使用以下預(yù)定義的標準字段

createdAt

updatedAt

deletedAt

使用 UTF-8 編碼

布爾值和數(shù)組不能使用 null

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

API 中的 date/time 應(yīng)該包含 timezone 信息 RFC3339

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

統(tǒng)一格式的國家，語言和錢幣

ISO 3166-1-alpha2 country codes

ISO 639-1 language code 或者 BCP 47

ISO 4217 currency codes

來自公眾號 無人深空，一個專注于技術(shù)和扯淡的公眾號，請不要關(guān)注

總結(jié)

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

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。