实践1:一类资源两个URL
一个 URL 表示该类型资源集合,另一个 URL 用来表示特定的资源元素。
# 资源集合:
/epics
# 资源元素:
/epics/5
实践2:使用一致的复数名词
避免混用复数和单数形式,只应该使用统一的复数名词来表达资源。
反例:
GET /story
GET /story/3
正例:
GET /stories
GET /stories/3
实践3:使用名词而不是动词
使用 Http 方法来表达动作(增、删、改、查):
- 增(POST:非幂等性):使用POST方法创建新的资源。
- 删(DELETE:幂等性):使用DELETE方法删除存在的资源。
- 改(PUT:幂等性):使用PUT或PATCH方法来更新已存在的资源。
- 查:使用GET方法读取资源。(GET:幂等性)
反例:
/getAllEpics
/getAllFinishedEpics
/createEpic
/updateEpic
正例:
GET /epics
GET /epics?state=finished
POST /epics
PUT /epics/5
实践4:将实际数据包装在data字段中
GET /epics
:在数据字段中返回 epic 资源列表
{
"data": [
{ "id": 1, "name": "epic1" }
, { "id": 2, "name": "epic2" }
]
}
GET /epic/1
:在数据字段中返回 id 为 1 的 epic 对象
{
"data": {
"id": 1,
"name": "epic1"
}
}
PUT,POST 和 PATCH 请求的有效负荷还应包含实际对象的数据字段。
优点:
- 还有空间扩展元数据
- 一致性
- 兼容 JSON API 标准
资源命名
- Controller 类继承于 ControllerBase,Controller 添加了对视图的支持,因此它更适合用于处理 MVC Web 页面,而不是 Web API。但是如果你的 Controller 需要同时支持 MVC Web 页面和 Web API,那么这时候就应该继承于 Controller 这个类。
- ControllerBase 类提供了很多用于处理 HTTP 请求的属性和方法。 例如,ControllerBase.CreatedAtAction 返回 201 状态代码。关于 ControllerBase 的属性和方法的详细列表,请查看官方参考文档。