文档章节

rest

木云凌
 木云凌
发布于 2016/03/22 14:46
字数 1032
阅读 26
收藏 1

1.使用名词而不是动词


Resource

资源


GET

POST

创建 PUT

修改 DELETE

/cars 返回 cars集合 创建新的资源 批量更新cars 删除所有cars

/cars/711 返回特定的car 该方法不允许(405) 更新一个指定的资源 擅长指定资源

不要使用:


/getAllCars

/createNewCar

/deleteAllRedCars


 


2.Get方法和查询参数不应该涉及状态改变


使用PUT, POST 和DELETE 方法 而不是 GET 方法来改变状态,不要使用GET 进行状态改变:


GET /users/711?activate 

GET /users/711/activate



3.使用复数名词


不要混淆名词单数和复数,为了保持简单,只对所有资源使用复数。


/cars 而不是 /car

/users 而不是 /user

/products 而不是 /product

/settings 而部署 /setting


 


4. 使用子资源表达关系


如果一个资源与另外一个资源有关系,使用子资源:


GET /cars/711/drivers/ 返回 car 711的所有司机

GET /cars/711/drivers/4 返回 car 711的4号司机


 


5.使用Http头声明序列化格式


在客户端和服务端,双方都要知道通讯的格式,格式在HTTP-Header中指定


Content-Type 定义请求格式

Accept 定义系列可接受的响应格式


 


6.使用HATEOAS


Hypermedia as the Engine of Application State 超媒体作为应用状态的引擎,超文本链接可以建立更好的文本浏览:


{

  "id": 711,

  "manufacturer": "bmw",

  "model": "X5",

  "seats": 5,

  "drivers": [

   {

    "id": "23",

    "name": "Stefan Jauker",

    "links": [

     {

     "rel": "self",

     "href": "/api/v1/drivers/23"

    }

   ]

  }

 ]

}

注意href指向下一个URL


7.为集合提供过滤 排序 选择和分页等功能


Filtering过滤:


使用唯一的查询参数进行过滤:


GET /cars?color=red 返回红色的cars

GET /cars?seats<=2 返回小于两座位的cars集合


Sorting排序:


允许针对多个字段排序


GET /cars?sort=-manufactorer,+model


这是返回根据生产者降序和模型升序排列的car集合


Field selection


移动端能够显示其中一些字段,它们其实不需要一个资源的所有字段,给API消费者一个选择字段的能力,这会降低网络流量,提高API可用性。


GET /cars?fields=manufacturer,model,id,color


 


Paging分页


使用 limit 和offset.实现分页,缺省limit=20 和offset=0;


GET /cars?offset=10&limit=5


为了将总数发给客户端,使用订制的HTTP头: X-Total-Count.


链接到下一页或上一页可以在HTTP头的link规定,遵循Link规定:


Link: <https://blog.mwaysolutions.com/sample/api/v1/cars?offset=15&limit=5>; rel="next",

<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=50&limit=3>; rel="last",

<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=0&limit=5>; rel="first",

<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=5&limit=5>; rel="prev",


 


8.版本化你的API


使得API版本变得强制性,不要发布无版本的API,使用简单数字,避免小数点如2.5.


一般在Url后面使用?v


/blog/api/v1


 


9. 使用Http状态码处理错误


如果你的API没有错误处理是很难的,只是返回500和出错堆栈不一定有用


Http状态码提供70个出错,我们只要使用10个左右:


200 – OK – 一切正常

201 – OK – 新的资源已经成功创建

204 – OK – 资源已经成功擅长


304 – Not Modified – 客户端使用缓存数据


400 – Bad Request – 请求无效,需要附加细节解释如 "JSON无效"

401 – Unauthorized – 请求需要用户验证

403 – Forbidden – 服务器已经理解了请求,但是拒绝服务或这种请求的访问是不允许的。

404 – Not found – 没有发现该资源

422 – Unprocessable Entity – 只有服务器不能处理实体时使用,比如图像不能被格式化,或者重要字段丢失。


500 – Internal Server Error – API开发者应该避免这种错误。


使用详细的错误包装错误:


{

  "errors": [

   {

    "userMessage": "Sorry, the requested resource does not exist",

    "internalMessage": "No car found in the database",

    "code": 34,

    "more info": "http://dev.mwaysolutions.com/blog/api/v1/errors/12345"

   }

  ]

}

10.允许覆盖http方法


一些代理只支持POST 和 GET方法, 为了使用这些有限方法支持RESTful API,需要一种办法覆盖http原来的方法。


使用订制的HTTP头 X-HTTP-Method-Override 来覆盖POST 方法.


本文转载自:http://www.jdon.com/soa/10-best-practices-for-better-restful-api.html

木云凌

木云凌

粉丝 14
博文 87
码字总数 32629
作品 0
广州
高级程序员
私信 提问
REST another WebService???

一、什么是REST REST stands for Representational State Transfer. (It is sometimes spelled "ReST".) It relies on a stateless, client-server, cacheable communications protocol -- a......

Oscarfff
2015/12/19
94
0
第貳章學題 Lisp 3rd Edition, Winston & Horn

2-1: Each of the following things may be an atom, a list, or neither. Identify each accordingly. ATOM (THIS IS AN ATOM) (THIS IS AN EXPRESSION) ((A B) (C D) 3 (3) (LIST 3) (/ (+......

莊博堯
2012/01/18
137
0
Web Services(3)-使用CXF开发REST 服务

REST服务介绍 REST 全称是 Representational State Transfer (表述性状态转移), 它是Roy Fielding 博士在2000年写的一篇关于软件架构风格的论文, 简称REST 服务 REST 本质上是使用URL来访问资...

陈小扁
2016/03/28
148
0
Arquillian REST Extension 1.0.0.Alpha4 发布

Arquillian REST Extension 1.0.0.Alpha4 发布,发行细节请看: Component Arquillian REST Extension Version 1.0.0.Alpha4 view tag Release date 2015-11-05 Released by Aslak Knutsen ......

叶秀兰
2015/11/10
388
1
体验Django REST framework,解读REST架构风格

因为项目中使用了REST API,所以对REST架构风格做了一些研究。如果有对REST架构风格还不了解,或者一知半解的朋友,可以读读我的另一篇文章《那些年,我们一起误解过的REST》。 一开始在项目...

aa按时发生
2018/09/04
0
0

没有更多内容

加载失败,请刷新页面

加载更多

3_数组

3_数组

行者终成事
今天
7
0
经典系统设计面试题解析:如何设计TinyURL(二)

原文链接:https://www.educative.io/courses/grokking-the-system-design-interview/m2ygV4E81AR 编者注:本文以一道经典的系统设计面试题:《如何设计TinyURL》的参考答案和解析为例,帮助...

APEMESH
今天
7
0
使用logstash同步MySQL数据到ES

概述   在生成业务常有将MySQL数据同步到ES的需求,如果需要很高的定制化,往往需要开发同步程序用于处理数据。但没有特殊业务需求,官方提供的logstash就很有优势了。   在使用logstas...

zxiaofan666
今天
10
0
X-MSG-IM-分布式信令跟踪能力

经过一周多的鏖战, X-MSG-IM的分布式信令跟踪能力已基本具备, 特点是: 实时. 只有要RX/TX就会实时产生信令跟踪事件, 先入kafka, 再入influxdb待查. 同时提供实时sub/pub接口. 完备. 可以完整...

dev5
今天
7
0
OpenJDK之CyclicBarrier

OpenJDK8,本人看的是openJDK。以前就看过,只是经常忘记,所以记录下 图1 CyclicBarrier是Doug Lea在JDK1.5中引入的,作用就不详细描述了,主要有如下俩个方法使用: await()方法,如果当前线...

克虏伯
今天
8
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部