RESTful Android API 定义
约定
回复中默认包含标头:
Content-Type: application/json;charset=UTF-8异步操作以(*)号标记
大多数异步操作同时只能有一个任务在进行,以上传联系人为例:
客户端每次提交 POST /persons/uploader服务器放弃进行中的上传任务而新建;
客户端可以先访问GET /persons/uploader 获得当前是否有正在上传的任务;
服务器遇到错误的时候会将任务挂起,返回错误原因,客户端可以选择重试或者终止;
客户端接收到任务失败的响应后,如果响应中不包括retry的链接,则不应该重试;
授权失败将返回403 Forbidden,客户端应该提示用户进行授权,同时进行重试。
联系人
URI 定义
接口 | HTTP method | URI |
---|---|---|
获取所有联系人 | GET | /persons?pagesize={pagesize}&start={start} |
删除所有联系人* | POST | /persons/purge |
上传联系人* | POST | /persons/uploader |
获取联系人信息 | GET | /persons/{id} |
新建联系人 | POST | /persons |
编辑联系人 | PUT | /persons/{id} |
删除联系人 | DELETE | /persons/{id} |
示例
获取所有联系人
GET /persons?pagesize=10&start=0
200 OK
{
total: 100,
links:
[
{rel: "self", href: "/persons?pagesize=10&start=10"},
{rel: "pre", href: "/persons?pagesize=10&start=0"},
{rel: "next", href: "/persons?pagesize=10&start=20"}
],
persons:
[
{
link: {rel: "self", href: "/person/1"}, id: "1", name: "Jack"//...
},
{
link: {rel: "self", href: "/person/2"}, id: "2", name: "Lucy"//...
}
]
}
删除所有联系人*
GET /persons/purge
200 OK
{
link: {rel: "self", href="/persons/purge/0"} //一般不关心上次任务的状态,所以表述中没有捎带其状态
}
不使用DELETE /persons, /persons资源仍然可以访问
POST /persons/purge
202 Accpeted
{
link: {rel: "self", href="/persons/purge/0"}
}
GET /persons/purge/0
进行中
200 OK
{
link: {rel: "self", href="/persons/purge/0"},
state: "pending",
percent: "30"
}
成功
303 See Other
Location: "/persons"
{
link: {rel: "self", href="/persons/purge/0"},
state: "done"
}
失败
200 OK
{
links:
[
{rel: "self", href="/persons/purge/0"},
{rel: "retry", href="/persons/purge/0"}
]
state: "failed",
reason: "XXX",
}
重试
PUT /persons/purge/0
200 OK
终止
DELETE /persons/purge/0
200 OK
上传联系人*
GET /persons/uploader
200 OK
{
link: {rel: "self", href="/persons/uploader/0"}}
}
POST /persons/uploader
[
{name: "Jack"},
{name: "Lucy"},
{name: "Lily"}
]
202 Accepted
{
link: {rel: "self", href="/persons/uploader/0"}}
}
GET /persons/uploader
进行中
200 OK
{
link: {rel: "self", href="/persons/uploader/0"},
state: "pending",
percent: "30"
}
成功
303 See Other
Location: "/persons"
{
link: {rel: "self", href="/persons/uploader/0"},
state: "done"
}
失败
200 OK
{
links:
[
{rel: "self", href="/persons/uploader/0"},
{rel: "retry", href="/persons/uploader/0"}
]
state: "failed",
reason: "XXX"
}
重试
PUT /persons/uploader/0
200 OK
终止
DELETE /persons/uploader/0
200 OK
获取联系人信息
GET /person/1
200 OK
{
link: {rel: "self", href: "/person/1"}, id: "1", name: "Jack"//...
}
新建联系人
POST /persons
{
name: "Jack"//...
}
201 Created
{
link: {rel: "self", href: "/person/1"}, id: "1", name: "Jack"//...
}
编辑联系人
PUT /person/1
{
name: "Jack"//...
}
200 OK
{
link: {rel: "self", href: "/person/1"}, id: "1", name: "Jack"//...
}
删除联系人
DELETE /person/1
200
{
name: "Jack"//...
}