restful api响应设计个人心得

以下内容以json api规范为基础

返回数据

将实际数据放在data中，例如

普通单数data

GET /epics/1

响应

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

普通复数data

GET /epics

响应

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

如何表达关系

GET /epics/1

返回嵌入式规范的数据，这里选用嵌入式的原因：

• 对客户来说最方便。 是可以直接通过关系来获取实际数据。其他方式需要客户端自行拼接

响应

{
	"data": [{
		"id": 1,
		"name": "用户故事1",
		"epic": {
			"id": 5,
			"name": "epic5"
		},
		"subTask": [{
			"id": 12,
			"name": "子任务12"
		}, {
			"id": 13,
			"name": "子任务13"
		}]
	}]
}

分页
此处涉及两种分页形式

1、基于偏移量的

# 返回30至45的epics
/epics?offset=30&limit=15 
# 如果未填参数，则可使用默认值（offset=0， limit=100 ）
/epics

响应