URI設計原則,API設計原則

我們設計的REST API真的nice麼？

優雅型：http://api.exapmle.com/louvre/da-vinci/mona-lisa

盧浮宮/達芬奇/蒙娜麗莎

中庸型：http://58.com/bj/ershou/310976

北京/二手頻道/帖子ID

謝特型：http://api.example.com/68dd0-a9d3-11e0-9f1c 

不知道什麼鬼

 

本文將分享URI設計的一些原則。

 

1. URI的末尾不要添加「/」

多一個斜槓，語義徹底不一樣，到底是目錄，仍是資源，仍是不肯定而多作一次301跳轉？

負面case：http://api.canvas.com/shapes/ 

正面case：http://api.canvas.com/shapes

 

2. 使用「-」提升URI的可讀性

目的是使得URI便於理解，用「-」來鏈接單詞

正面case：http://api.example.com/blogs/my-first-post

 

3. 禁止在URL中使用「_」

目的是提升可讀性，「_」可能被文本查看器中的下劃線特效遮蔽

負面case：http://api.example.com/blogs/my_first_post

別爭，看到效果就明白了

 

4. 禁止使用大寫字母

RFC 3986中規定URI區分大小寫，但別用大寫字母來爲難程序員了，既不美觀，又麻煩

負面case：http://api.example.com/My-Folder/My-Doc 

正面case：http://api.example.com/my-folder/my-doc 

 

5. 不要在URI中包含擴展名

應鼓勵REST API客戶端使用HTTP提供的格式選擇機制Accept request header

正面case：http://58.com/bj/ershou/310976

一個case：http://58.com/bj/ershou/310976x.shtml

 

6. 建議URI中的名稱使用複數

額，樓主不知道爲什麼會有這麼奇怪的建議

正面case：http://api.college.com/students/3248234/courses

負面case：http://api.college.com/student/3248234/course

 

最後，給後端研發工程師一個建議：清晰優雅的 RESTful API是爲調用者編寫的，別無腦隨意定義一些shit同樣的URI給移動/前端工程師使用，當心生命有危險。

 

原文：http://blog.restcase.com/7-rules-for-rest-api-uri-design

做者：Guy Levin 

 

你見過一些什麼奇葩的URI？