The orientation(定位) for APIs is to think about design choices from the application developer’s point of view. The application developer is the lynchpin(關鍵) of the entire API strategy.

  • Application developer 是設計API時所參考的核心,因為他們才是最終API的使用者,在設計API時要從他們的使用角度去思考。

The number one principle in pragmatic RESTful design is : keep simple things simple.

  • RESTful的設計哲學就是簡單的事就應該保持簡單。

The point is that developers probably don’t need the chart to understand how the API behaves. They can experiment with and learn the API without the documentation.

  • 簡單的設計哲學所要達成的目的就是寫出來的API不必讓developer須要花太多精力去學習了解API行為,他們只要靠著自己試驗而不需要文件就可以知道如何使用API。底下有三大原則用來達成API簡單化的目的。

Rule 1. Use two base URLs per resource.

  • 第一點: 一個resource 代表一個Object,只需要兩個base url便可以運作該resource,其一是針對resource整體,另一是針對該resource的特定個體。
  • For Example:

Base URL 1. /dogs

Base URL 2. /dogs/1234

  • Dogs  是該URLResource,第一個URL應用對象是所有的狗;第二個對象編號為1234的狗。

Rule 2. Keep verbs out of your base URLs

  • 第二點: URL 中我們以resource作為欲操作的Object,因此應該避免用動詞作為API名稱,這將會使API名稱變得複雜且清單冗長,對developer來說在選擇API時將會形成負擔
  • For Example:

/getAllDogs : 取得所有狗狗清單

/verifyVeterinarianLocation : 驗證獸醫地址

/getSittingDog: 取得正坐著的狗狗清單

  • 動詞加名詞以及修飾詞將使得API URL清單變得多且長。

 

Rule 3. HTTP verbs to operate on the collections and elements.

  • 第三點: 利用HTTP Method來對Resource進行CRUD( Create, Read, Update, delete)
  • HTTP 4Method搭配Resource base URL便可以讓Developer輕易了解我們可以對每一個Resource做哪些事情,這樣就不用像第二點一樣用動詞列出每一支API造成視覺與記憶負擔。

 

Resource

POST( Create)

GET (Read)

PUT (Update)

DELETE (Delete)

/dogs

Create a new Dog

List dogs

Update all dogs

Delete all dogs

/dogs/1234

Error

Show one dog

Update one dog

Delete one dog

 

[參考] Web API Design - Crafting Interfaces tgat Develoers Love

      https://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf

201865日星期二

文章標籤
創作者介紹
創作者 jackterrylau 的頭像
jackterrylau

儒道哲學的浪漫人生

jackterrylau 發表在 痞客邦 留言(0) 人氣()