Apigee Pragmatic API Design 3 – API Version and Error Handling

API Version Number

Never release an API without a version and make the version mandatory(強制的).

• API 都應該有版本號碼(Version Number)

API can use Version number placed somewhere in the middle of the URL.

• API 可以在URL中放入適當的Version Number

Specify the version with a ‘v’ prefix and don’t use the dot notation like V1.2 because it implies(意味) a granularity(顆粒度) of versioning that doesn’t work well with APIs. API is an interface not an implementation. Stick with(堅持做) V1, V2, and so on.

• API Version Number應該用 V + Integer Number(如:V1, V2)作為版本號碼，而不要使用帶小數點的版號。小數點的版號會使的API變動粒度加大，不利app developer接取API，要記住API是Interface，而不是Implementation，版號的存在必需盡量不影響API的使用方式。

Move Version Number all the way to the left in the URL so that it has the highest scope.

• API Version應該盡量在URL的最左邊，以含蓋最大的API Function視野。
• For Example,
• https://dogshop.com.tw/gogoapi/v2/dogs/1234

How many versions should we maintain? Maintain at least one version back.

• API版本不要同時維持太多版本，除了現行版本外，最多再維護上一版本即可。如現在是V3，那只要同時保留V2版本即可。

Should version and format be in URLs or headers?

  If it changes the logic you write to handle the response, put it in the URL so you can see it easily.

  If it doesn’t change the logic for each response, like OAuth information, put it in the header.

• 這裡告訴我們關於API的某些元素(在這邊是API的Version number 和 data format) 應該放在URL或Header好的判斷準則是什麼。
• 如果該元素(Version Number)代表API Response 邏輯改變(如:回傳欄位變多)，那就應該放置在URL中，讓developer可以清楚辨認。
• 如果該元素(Data Format)不會改變API Response邏輯，那放在URL Header即可。

API Error Handling

The error message returned in the payload as verbose as possible as below,

{

  “Status” : ”Standard HTTP status Code.”,

  “DeveloperMessage” : “Verbose, plain language description of the problem for the app developer with hints about how to fix it .”,

  “UserMessage” : ”Pass this message on to the app user if needed.”,

  “ErrorCode” : ”Defined code for developer to mapping with developer message ”,

  “MoreInfo” : “ Refer API Document ”

}

• Status : HTTP Code, 建議放入Response body。
• Developer Message, 即Error message，是提供給Developer看以方便他們知道call API的錯誤在哪而修正，這是必要的。
• User Message, 這不是必要的，通常前端developer可以根據自己需求定義自己的app user error message，這樣做對前端接API的developer來說會更有彈性。
• Error Code, 對應到Error message for developer，可以清楚代表錯誤狀態，方便快速debug, 這是必要的。
• More Info, 一般是參考到API文件的Link，以提供app developer更多API使用訊息，建議放入response body。

Choose HTTP Status Code

There are really only 3 outcomes in the interaction between an app and an API,

Success / Client Error / Server Error .

• App 呼叫API會得到3種可能結果,
• Success : API return OK.
• Client Error :  App端發生錯誤.
• Server Error : API Server端發生錯誤.

Start by using the following 3 codes. If you need more, add them. But you shouldn’t need to go beyond 8.

200 – OK (Success)

400 – Bad Request (Client Error)

500 – Internal Server Error (Server Error)

if you’re not comfortable reduciong all your error conditions to these 3, try picking among these additional 5,

201 – Created

304 – Not Modified

404 – Not Found

401 – Unauthorized

403 – Forbidden

• 200/400/500 是三個絕對API必要的HTTP Status Code，如果這些Status Code不足以表達API code的Status，可以選擇性的再多加入201/304/401/403/404 等HTTP Status Code.
• 其他常見的Http Code還有502/504/302/409 ….

2018年6月8日星期五