RESTful Android API 定义

约定

• 回复中默认包含标头： Content-Type: application/json;charset=UTF-8

• 异步操作以（*）号标记

• 大多数异步操作同时只能有一个任务在进行，以上传联系人为例：

  1. 客户端每次提交 POST /persons/uploader服务器放弃进行中的上传任务而新建；

  2. 客户端可以先访问GET /persons/uploader 获得当前是否有正在上传的任务；

  3. 服务器遇到错误的时候会将任务挂起，返回错误原因，客户端可以选择重试或者终止；

  4. 客户端接收到任务失败的响应后，如果响应中不包括retry的链接，则不应该重试；

• 授权失败将返回403 Forbidden，客户端应该提示用户进行授权，同时进行重试。

联系人

URI 定义

示例

获取所有联系人

GET /persons?pagesize=10&start=0

1. 200 OK
2. {
3. total: 100,
4. links:
5. [
6. {rel: "self", href: "/persons?pagesize=10&start=10"},
7. {rel: "pre", href: "/persons?pagesize=10&start=0"},
8. {rel: "next", href: "/persons?pagesize=10&start=20"}
9. ],
10. persons:
11. [
12. {
13. link: {rel: "self", href: "/person/1"}, id: "1", name: "Jack"//...
14. },
15. {
16. link: {rel: "self", href: "/person/2"}, id: "2", name: "Lucy"//...
17. }
18. ]
19. }

删除所有联系人*

GET /persons/purge

1. 200 OK
2. {
3. link: {rel: "self", href="/persons/purge/0"} //一般不关心上次任务的状态，所以表述中没有捎带其状态
4. }

不使用DELETE /persons, /persons资源仍然可以访问

POST /persons/purge

1. 202 Accpeted
2. {
3. link: {rel: "self", href="/persons/purge/0"}
4. }

GET /persons/purge/0

进行中

1. 200 OK
2. {
3. link: {rel: "self", href="/persons/purge/0"},
4. state: "pending",
5. percent: "30"
6. }

成功

1. 303 See Other
2. Location: "/persons"
3. {
4. link: {rel: "self", href="/persons/purge/0"},
5. state: "done"
6. }

失败

1. 200 OK
2. {
3. links:
4. [
5. {rel: "self", href="/persons/purge/0"},
6. {rel: "retry", href="/persons/purge/0"}
7. ]
8. state: "failed",
9. reason: "XXX",
10. }

重试

PUT /persons/purge/0

1. 200 OK

终止

DELETE /persons/purge/0

1. 200 OK

上传联系人*

GET /persons/uploader

1. 200 OK
2. {
3. link: {rel: "self", href="/persons/uploader/0"}}
4. }

POST /persons/uploader

[ {name: "Jack"}, {name: "Lucy"}, {name: "Lily"} ]

1. 202 Accepted
2. {
3. link: {rel: "self", href="/persons/uploader/0"}}
4. }

GET /persons/uploader

进行中

1. 200 OK
2. {
3. link: {rel: "self", href="/persons/uploader/0"},
4. state: "pending",
5. percent: "30"
6. }

成功

1. 303 See Other
2. Location: "/persons"
3. {
4. link: {rel: "self", href="/persons/uploader/0"},
5. state: "done"
6. }

失败

1. 200 OK
2. {
3. links:
4. [
5. {rel: "self", href="/persons/uploader/0"},
6. {rel: "retry", href="/persons/uploader/0"}
7. ]
8. state: "failed",
9. reason: "XXX"
10. }

重试

PUT /persons/uploader/0

1. 200 OK

终止

DELETE /persons/uploader/0

1. 200 OK

获取联系人信息

GET /person/1

1. 200 OK
2. {
3. link: {rel: "self", href: "/person/1"}, id: "1", name: "Jack"//...
4. }

新建联系人

POST /persons

{ name: "Jack"//... }

1. 201 Created
2. {
3. link: {rel: "self", href: "/person/1"}, id: "1", name: "Jack"//...
4. }

编辑联系人

PUT /person/1

{ name: "Jack"//... }

1. 200 OK
2. {
3. link: {rel: "self", href: "/person/1"}, id: "1", name: "Jack"//...
4. }

删除联系人

DELETE /person/1

1. 200
2. {
3. name: "Jack"//...
4. }

参考

HTTP Method Definitions