Skip to content

Instantly share code, notes, and snippets.

@dz1984

dz1984/Web_API_Design_Tip.md

Last active August 29, 2015 14:04
Show Gist options
  • Save dz1984/6e4681c9f2c416bb2fb8 to your computer and use it in GitHub Desktop.
Save dz1984/6e4681c9f2c416bb2fb8 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
Web_API_Design_Tip.md

Pragmatic REST(實用REST)設計原則

Pragmatic REST 設計原則是能開發者生產力最佳化的API。問題是怎樣設計能為 App 開發者帶來幫助。

名詞大推，動詞不推

  • 保持URLs設計簡單直覺，這會讓你的 API 容易使用。
  • URLs 遠離動詞。
  • 使用 HTTP verbs 操作 Collectons 和 Elements。

複數名詞和具體名詞

  • 直覺 API 使用複數名詞、具體命名，而不是單數、抽象命名。

單一化組合

  • Resource 與 Resource 之間關係複雜。 /resource/identifier/resource

錯誤處理

  • 為何良好錯誤設計對 API 設計者特別重要？

  • 如何考量在實用REST方式的錯誤？

  • 幾個最佳實作：

    • 使用 HTTP 狀態碼，需要幾個狀態碼? 其實只要三個結果： Success(200 - OK)、Client Error(400 - Bad Request)、Server Error(500 - Internal Server Error)，若不夠可以增加，但別超過8個。額外增加5個狀態碼， 201 - Created、304 - Not Modified、404 - Not Found、401 - Unauthorized、403 - Forbidden。
    • 在可負擔情況下，傳回詳細且有效地訊息。
    • 編碼給程式
    • 文字訊息給人類
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment