Partial response allows you to give developers just the information they need. Support partial response by adding optional fields in a comma-delimited list. It cuts down on bandwidth issues.

  • Partial response可以只回傳developers 在一次request中所需要知道的資訊,而不必每次都回傳所有資料欄位給developersrequest. 假若API可以調出一個人的基本資料及聯絡資訊和所得資訊,若developer只要所得資訊,則只要在API Request 中額外加進一個Optional fields並用逗號指定所要的所得資訊欄位,那API就不用每次都回傳個人包含所得在內的所有資料。
  • For Example,
  •  , 傳回狗狗資料清單,但只要每隻狗狗名稱顏色與位置資訊,其餘資訊不用。
  • Partial response可以有效減少頻寬不足的問題。

 

Use limit and offset to make it easy for developers to paginate object.

  • 為了不要在一次request中回傳所有資料庫資料給User,我們可以在API Request中使用Limit Offset 參數將回傳物件分頁(Paginate objects),這在使用者的request所得到的回傳資料量很大時適時顯示適量資訊給使用者,分頁顯示資料也是partial response的一種型式。
  • For Example,
  • /dogs?limit=25&offset=50 ,一次顯示25筆資料,資料頁是50,也就是顯示第50頁的資料,且一頁最多有25筆資料。

 

Actions like the following are your clue(提示;線索) that you might not be dealing with a resource response. Calculate, Translate, and Convert. None involve resources returned from a database. In these cases, use verbs not nouns.

  • 如果API Response並不是直接地從資料庫中抓取resource然後回傳給user,而是經作某些操作(Action),然後產生結果再放進Response中回傳給User,那麼API URL中應該使用Verbs來指明該APIResponse不是直接來自Database­,而是透過Verbs的運算產生。通常這些Verbs:Calculate/Translate/Convert.
  • Fox Example, An API to convert 100 euros to Chinese Yen.
  •  

 

We recommend that you support more than one format and working with JSON as the default.

  • API 建議支援多種回應類文件格式,並且以JSON為預設。

 

Follow JavaScript conventions for naming attributes.

  • Json的每一個資料欄位或屬性(attribute)名稱的命名樣式應該與JavaScript的命名慣例一致。如: createAt

 

Consolidate all API requests under one API subdomain. In keeping with the spirit of REST, your developer portal should follow this pattern, developers.your-top-level-domain.xxx

  • API 在你的網站主要domain( top-level domain)下要有獨立的自己的domain.
  • For Example,

Facebook domain : www.facebook.com

Facebook API subdomain( developer portal): developers.facebook.com

 

2018610日星期日

arrow
arrow

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