RESTful Android

RESTful Android API 定义

约定

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

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

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

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

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

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

    4. 客户端接收到任务失败的响应后，如果响应中不包括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

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

删除所有联系人*

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
  3. {
  4.     link: {rel: "self", href="/persons/uploader/0"}}
  5. }

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
  3. {
  4.     link: {rel: "self", href: "/person/1"}, id: "1", name: "Jack"//...
  5. }

新建联系人

POST /persons

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

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

编辑联系人

PUT /person/1

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

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

删除联系人

DELETE /person/1

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

参考

HTTP Method Definitions

【推广】 免费学中医，健康全家人
原文地址：https://www.cnblogs.com/zhengwenwei/p/3570717.html