URI设计原则

以下是与 REST API 相关的重要术语：

资源（Resource）是一个对象或对某物的表示。它有一些相关联的数据，并有一组方法进行操作。例如：动物，学校和员工是资源。这些资源都有着删除，添加，更新操作。
集合（Collection）是一系列资源，例如：公司集合是很多公司的集合。
URL（统一资源定位符）是一种路径，可以通过它定位资源并且也可以对它执行一些动作

URI的末尾不要添加/
多一个斜杠，语义完全不同，究竟是目录，还是资源，还是不确定而多做一次301跳转？
负面case：http://api.canvas.com/shapes/
正面case：http://api.canvas.com/shapes
使用-提高URI的可读性
目的是使得URI便于理解，用“-”来连接单词
正面case：http://api.example.com/blogs/my-first-post
禁止在URL中使用_
目的是提高可读性，“_”可能被文本查看器中的下划线特效遮蔽
负面case：http://api.example.com/blogs/my_first_post
禁止使用大写字母
RFC 3986中规定URI区分大小写，但别用大写字母来为难程序员了，既不美观，又麻烦
负面case：http://api.example.com/My-Folder/My-Doc
正面case：http://api.example.com/my-folder/my-doc
不要在URI中包含扩展名
应鼓励REST API客户端使用HTTP提供的格式选择机制Accept request header
负面case：http://58.com/bj/ershou/310976x.shtml
正面case：http://58.com/bj/ershou/310976
建议URI中的名称使用复数
正面case：http://api.college.com/students/3248234/courses
负面case：http://api.college.com/student/3248234/course

每个 URL 代表一种资源（Resource），所以 URL 中只能有名词，不能有动词

资源在 API 端点中应该总是复数
/addNewEmployee 包含了操作 addNew 和资源名称 Employee

方法 GET 路径 /companies 是获取所有公司的列表。
方法 GET 路径 /companies/34 是获取公司34的详细信息。
方法 DELETE 路径 /companies/34 是删除公司34

GET /companies/3/employees 可以取得编号为3的公司的员工列表
GET /companies/3/employees/45 可以取得编号为3的公司的45号员工的细节信息
DELETE /companies/3/employees/45 可以删除编号为3的公司的45号员工
POST /companies 可以创建一个新公司并返回新创建公司的细节信息

#结论：路径应该包含资源的复数形式，HTTP 方法应该定义成各种行为在资源上执行。
#URL 是一个句子，其中资源是名词，HTTP 方法是动词。

HTTP 方法 (动词)

GET 方法从资源请求数据，不产生多余结果。
例如： /companies/3/employees 会返回公司3的所有雇员列表。

POST 方法请求服务器在数据库中创建资源，这主要用于提交 Web 表单时
POST 是非幂等的，这意味着多个请求将会有不同的效果。
例如： /companies/3/employees 创建一个公司3的新雇员。

PUT 方法请求服务器更新资源或创建资源（如果不存在的话）。
例如： /companies/3/employees/john 将请求服务器在公司3的雇员集合中更新或在不存在的情况下创建关于 john 的资源.
PUT 是幂等的，这意味着多次请求具有相同的效果。

DELETE 方法将请求的资源或实例从数据库中删除。
 /companies/3/employees/john/ 将请求服务器从公司3的雇员集中删除 john 资源。

搜索、排序、过滤和分页
- 排序(sorting)
  例如，GET /companies?sort=rank_asc 将根据等级以升序的方式对公司进行排序。
- 过滤（Filtering）
  例如，GET /companies?category=banking&location=india 将根据公司类别为银行以及所处位置为印度来过滤公司的列表数据。
- 搜索（Searching）
  例如，API 端点应当是 GET /companies?search=Digital Mckinsey。
- 分页（Pagination）
  例如，GET /companies?page=23 表示获取第 23 页的公司列表。
  
  如果在 GET 方法中附加了很多查询参数，会造成 URI 太长，服务器可能会响应 414 的 HTTP 状态，表示这个 URI 太长，在这种情况下，我们也可以将参数传递给 POST 方法的请求体中。
版本控制
例子 http://api.yourservice.com/v1/companies/34/employees
它的路径中有API的版本号。如果有任何重大的中断更新，我们可以将新的API集命名为v2或v1.x.x

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