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日星期五

相关文章