RESTful API规范

实践1：一类资源两个URL

一个 URL 表示该类型资源集合，另一个 URL 用来表示特定的资源元素。

1
2

# 资源集合：
/epics

1
2

# 资源元素：
/epics/5

实践2：使用一致的复数名词

避免混用复数和单数形式，只应该使用统一的复数名词来表达资源。

反例：

1
2

GET /story
GET /story/3

正例：

1
2

GET /stories
GET /stories/3

实践3：使用名词而不是动词

使用 Http 方法来表达动作（增、删、改、查）：

1. 增（POST：非幂等性）：使用POST方法创建新的资源。
2. 删（DELETE：幂等性）：使用DELETE方法删除存在的资源。
3. 改（PUT：幂等性）：使用PUT或PATCH方法来更新已存在的资源。
4. 查：使用GET方法读取资源。（GET：幂等性）

反例：

1
2
3
4

/getAllEpics
/getAllFinishedEpics
/createEpic
/updateEpic

正例：

1
2
3
4

GET /epics
GET /epics?state=finished
POST /epics
PUT /epics/5

实践4：将实际数据包装在data字段中

GET /epics：在数据字段中返回 epic 资源列表

1
2
3
4
5
6

{
  "data": [
    { "id": 1, "name": "epic1" }
    , { "id": 2, "name": "epic2" }
  ]
}

GET /epic/1：在数据字段中返回 id 为 1 的 epic 对象

1
2
3
4
5
6

{
  "data": { 
    "id": 1, 
    "name": "epic1"
  }
}

PUT，POST 和 PATCH 请求的有效负荷还应包含实际对象的数据字段。

优点：

• 还有空间扩展元数据
• 一致性
• 兼容 JSON API 标准

资源命名

1. Controller 类继承于 ControllerBase，Controller 添加了对视图的支持，因此它更适合用于处理 MVC Web 页面，而不是 Web API。但是如果你的 Controller 需要同时支持 MVC Web 页面和 Web API，那么这时候就应该继承于 Controller 这个类。
2. ControllerBase 类提供了很多用于处理 HTTP 请求的属性和方法。 例如，ControllerBase.CreatedAtAction 返回 201 状态代码。关于 ControllerBase 的属性和方法的详细列表，请查看官方参考文档。

参考

GitHub REST API

https://developer.github.com/v3/