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

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"//...
}

参考

HTTP Method Definitions

RESTful Android,,5-wow.com