URI设计原则

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

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

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/310976x.shtml
   
   正面case：http://58.com/bj/ershou/310976

6. 建议URI中的名称使用复数
   
   正面case：http://api.college.com/students/3248234/courses
   
   负面case：http://api.college.com/student/3248234/course

7. 每个 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 方法是动词。
   

8. 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 资源。
   

9. 搜索、排序、过滤和分页

   • 排序(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 方法的请求体中。

10. 版本控制
    
    例子 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