Restful API 的设计规范
1. URIURI 表示资源,资源一般对应服务器端领域模型中的实体类。
资源集合与单个资源 /zoos //所有动物园 /zoos/1/animals //id为1的动物园内的所有动物 单个资源: /zoos/1 //id为1的动物园 /zoos/1;2;3 //id为1,2,3的动物园 避免层级过深的URI 对Composite资源的访问
2. RequestHTTP方法 GET /zoos GET /zoos/1 GET /zoos/1/employees POST: 创建单个资源。POST一般向“资源集合”型URI发起; POST /animals //新增动物 POST /zoos/1/employees //id为1的动物园的所有员工 PUT:更新单个资源(全量),客户端提供完整的更新后的资源。与之对应的是 PATCH,PATCH 负责部分更新,客户端提供要更新的那些字段。PUT/PATCH一般向“单个资源”型uri发起 PUT /animals/1 PUT /zoos/1 DELETE:删除 DELETE /zoos/1/employees/2 DELETE /zoos/1/employees/2;4;5 DELETE /zoos/1/animals //删除id为1的动物园内的所有动物 HEAD / OPTION 用的不多,就不多解释了。 安全性与幂等性 安全性和幂等性均不保证反复请求能拿到相同的response。以 DELETE 为例,第一次DELETE返回200表示删除成功,第二次返回404提示资源不存在,这是允许的。 复杂查询 Bookmarker GET /trades?status=closed&sort=created,desc 快捷方式: GET /trades#recently-closed // 或者 GET /trades/recently-closed Format
POST /v1/animal HTTP/1.1 Host: api.example.org Accept: application/json Content-Type: application/json Content-Length: 24 { "name": "Gir","animalType": "12" }
POST /login HTTP/1.1 Host: example.com Content-Length: 31 Accept: text/html Content-Type: application/x-www-form-urlencoded username=root&password=Zion0101
Content Negotiation
Accept:application/xml;q=0.6,application/atom+xml;q=1.0 q为各项格式的偏好程度
3. Response
{ "success":true,"data":{"id":1,"name":"xiaotuan"},}
分页response { "paging":{"limit":10,"offset":0,"total":729},"data":[{},{},{}...] } 4. 错误处理
对第三点的实现稍微多说一点:
在Controller层使用统一的异常拦截器:
常用的http状态码及使用场景: 5. 服务型资源除了资源简单的CRUD,服务器端经常还会提供其他服务,这些服务无法直接用上面提到的URI映射。如:
可以把这些服务看成资源,计算的结果是资源的presentation,按服务属性选择合适的HTTP方法。 GET /search?q=filter?category=file 搜索 GET /distance-calc?lats=47.480&lngs=-122.389&late=37.108&lnge=-122.448 POST /batch-publish-msg [{"from":0,"to":1,"text":"abc"},{}...] 6. 异步任务对耗时的异步任务,服务器端接受客户端传递的参数后,应返回创建成功的任务资源,其中包含了任务的执行状态。客户端可以轮训该任务获得最新的执行进度。 // 提交任务: POST /batch-publish-msg [{"from":0,{}...] // 返回: {"taskId":3,"createBy":"Anonymous","status":"running"} GET /task/3 {"taskId":3,"status":"success"} 如果任务的执行状态包括较多信息,可以把“执行状态”抽象成组合资源,客户端查询该状态资源了解任务的执行情况。 提交任务: POST /batch-publish-msg [{"from":0,{}...] 返回: {"taskId":3,"createBy":"Anonymous"} GET /task/3/status {"progress":"50%","total":18,"success":8,"fail":1} 7. API演进版本
用第一种,虽然没有那么优雅,但最明显最方便。 URI失效随着系统发展,总有一些API失效或者迁移,对失效的API,返回404 not found 或 410 gone;对迁移的API,返回 301 重定向。 (编辑:李大同) 【声明】本站内容均来自网络,其相关言论仅代表作者个人观点,不代表本站立场。若无意侵犯到您的权利,请及时与联系站长删除相关内容! |