9153人阅读
基础技术（16）
导读：安全是恒久的话题，对于基于WSDL和SOAP的Web Service，我们有WS-Security这样的安全规范来指导实现认证、授权、身份管理等安全需求。如何保证RESTful API的安全性呢。
关键词：&&
前面讲了好的，本文会继续探讨RESTful API的安全性问题。
InfoQ：安全是恒久的话题，对于基于和SOAP的Web Service，我们有WS-Security这样的安全规范来指导实现认证、授权、身份管理等安全需求。那么，有无成熟可用规范或实现框架呢？如何保证RESTful API的安全性呢？
李锟：保证RESTful&API的安全性，主要包括三大方面：
a)&对客户端做身份认证
b)&对敏感的数据做加密，并且防止篡改
c)&身份认证之后的授权
对客户端做身份认证，有几种常见的做法：
在请求中加签名参数
1.为每个接入方分配一个密钥，并且规定一种签名的计算方法。要求接入方的请求中必须加上签名参数。这个做法是最简单的，但是需要确保接入方密钥的安全保存，另外还要注意防范replay攻击。其优点是容易理解与实现，缺点是需要承担安全保存密钥和定期更新密钥的负担，而且不够灵活，更新密钥和升级签名算法很困难。
使用标准的HTTP身份认证机制
HTTP&Basic身份认证安全性较低，必须与HTTPS配合使用。HTTP&Digest身份认证可以单独使用，具备中等程度的安全性。
HTTP&Digest身份认证机制还支持插入用户自定义的加密算法，这样可以进一步提高API的安全性。不过插入自定义加密算法在面向互联网的API中用的不是很多。
这个做法需要确保接入方“安全域-用户名-密码”三元组信息的安全保存，另外还要注意防范replay攻击。
优点：基于标准，得到了广泛的支持（大量HTTP服务器端、客户端库）。在服务器端做HTTP身份认证的职责可以由Web&Server（例如Nginx）、App&Server（例如Tomcat）、安全框架（例如Spring&Security）来承担，对应用开发者来说是透明的。HTTP身份认证机制（RFC&2617）非常好地体现了“分离关注点”的设计原则，而且保持了操作语义的可见性。
2.缺点：这类基于简单用户名+密码机制的安全性不可能高于基于非对称密钥的机制（例如数字证书）。
使用OAuth协议做身份认证
OAuth协议适用于为外部应用授权访问本站资源的情况。其中的加密机制与HTTP&Digest身份认证相比，安全性更高。需要注意，OAuth身份认证与HTTP&Digest身份认证之间并不是相互取代的关系，它们的适用场景是不同的。OAuth协议更适合于为面向最终用户维度的API提供授权，例如获取隶属于用户的微博信息等等。如果API并不是面向最终用户维度的，例如像七牛云存储这样的存储服务，这并非是OAuth协议的典型适用场景。
3.对敏感的数据做加密，并且防止篡改，常见的做法有：
部署SSL基础设施（即HTTPS），敏感数据的传输全部基于SSL。&
仅对部分敏感数据做加密（例如预付费卡的卡号+密码），并加入某种随机数作为加密盐，以防范数据被篡改。
身份认证之后的授权，主要是由应用来控制。通常应该实现某种基于角色+用户组的授权机制，这方面的框架有不少（例如Spring&Security），不过大多数开发团队还是喜欢自己来实现相关功能。
李建业：我不认为安全是RESTful&API需要考虑的问题，事实上我觉得这是两个正交的问题。当然，如果使用RESTful&API来提供认证、授权和身份管理，那也算是双方有关系，但是这和其它风格的API设计所要考虑的问题似乎没什么区别，不值得特别注意。
但是在具体设计层面，这两者的“正交点”上似乎确实有些问题，因为REST是一个推崇状态无关原则的架构风格，而认证和授权通常基于第三方解决方案，所以往往会出现违背有状态约束的问题，这个地方我也没有特别的想法，当然这个困难和原问题关系不大。
至于WS-族的协议，我不太了解，不太能参与讨论。
丁雪丰：对于RESTful&API，常见的安全措施都是可以继续使用的。例如，为了防篡改，可以对全部参数进行签名；为了防范重放攻击可以在请求中增加一次性的Token，或者短时间内有效的Token；对内容加密可以实现数据防泄露……；对于DDoS攻击，各种HTTP流量清洗策略，都可以继续发挥作用，因为这就是基本的HTTP请求。
在授权和认证方面，OAuth&2.0已经基本成熟了，并且得到了广泛地应用。如果可以，接入第三方账户体系是个不错的选择，比如Google和Facebook的，国内的当然也有几个候选。
马钧：个人认为RESTful的安全性分为几个层次，在安全要求较高的场合，可以通过HTTPs这样的加密协议来保证网络层的安全，应用层的安全可以通过OAuth实现认证，而对于资源的访问授权，则只能依靠应用程序来实现了。
InfoQ：如何对RESTful API进行版本控制，请分享您认为实用的做法？
李锟：一个比较简单实用的做法是直接在URI中插入版本号，这样做允许多个版本的API并行运行。
另一个做法是在HTTP请求中加入自定义头信息，标明使用的版本号。不过这个做法其实对浏览器不够友好，简单地使用浏览器+HTML无法测试。
李建业：目前比较好的方式还是在uri设计中添加版本信息，其它方法都不如这个实用。
丁雪丰：个人认为最好的版本化，就是没有明显的版本。在对已发布的服务进行变更时，要尽量做到兼容，其中包括URI、链接和各种不同的表述的兼容，最关键的就是在扩展时不能破坏现有的客户端。例如，要变更一个参数，可以选择同时兼容新旧两种输入，或者保持老参数不动，提供一个新的参数，在文档中必须做出说明，不推荐新用户再继续使用之前的参数。
如果必须要进行不兼容的变更，那么可以选择标记不同的版本号，这时可以选择在路径或参数中增加版本信息。也有做法是增加HTTP标头，只是在调用时会稍有不便，推荐前两种方法。
马钧：RESTfulAPI的版本升级，尽量兼容之前的版本，保证原有的API都能正常工作，可以通过HTTP&301转跳到新的资源。另外一种实用的做法就是在url中保留版本号，同时提供多个版本供客户端使用，如&&或者&/v1/&这样。
InfoQ：HTTP1.1规范中给出的动词对于设计RESTful API够用吗？您在实际项目中会扩展自己的动词吗？在什么情况下需要扩展？
李锟：这个问题取决于设计者如何看待和设计资源。如果资源抽象做的很好，对于某个资源的任何操作，通常都能够映射到CRUD四个类别中。CRUD四个类别对于操作资源来说，绝大多数情况下是完备的。HTTP的GET/POST/PUT/DELETE四个方法，对于CRUD四个类别的操作来说是足够的，映射关系是Create-POST/Retrieve-GET/Update-PUT/Delete-DELETE。
我们通常不会选择创建自己的动词，这样做对于客户端开发者来说，需要更多的学习成本。如果在资源上定义的操作过多，我们会选择拆分出更多的资源。
李建业：一般是够用的，有时一些“不够用”的场景是由于我们没有设计出合理的资源，比如批量操作。但是，正如之前所说的那样，对于某些内部的、传统的（因此模型稳定且已知）系统，API提供者和调用者会有自已的固定动词表，此时没必要拘泥。另外，我不建议扩展动词，一旦扩展了动词，其实已经破坏了我之前说的*“尽可能少的先验信息”*，那么，扩展动词和重新设计动词的成本差别不大。基于这个考虑，我建议尽可能保持动词不变，除非你想重新设计动词表。
丁雪丰：一般情况下，常用的HTTP动词是够用的，并没有出现一定要自己扩展动词的情况。其实，最常用的也就是GET、POST、DELETE和PUT，而HEAD、OPTIONS、TRACE则基本用不太到。如果出现一时找不到合适的动词，安全幂等的操作用GET，其他都可以用POST，在设计资源时稍加考虑即可。
马钧：在我的实际项目中，只用到了POST，PUT，DELETE，GET这四个动词。
InfoQ：今年5月份发布的JAX-RS 2.0规范对于RSTfulAPI的设计最有价值的特性是哪个（些）? 它（们）用于解决什么问题？
李锟：REST开发框架RESTEasy项目负责人Bill&Burke，去年写了一篇文章介绍JAX-RS&2.0。
我同意Bill在文章中的观点，在JAX-RS&2.0增加的内容中，最重要的三部分为：
a)&Client&API——用来规范化JAX-RS客户端的开发方式。
b)&Server-side&Asynchronous&HTTP——用来实现服务器端推送功能，而不需要依靠低效的轮询方式。
c)&Filters&and&Interceptors——用来分离关注点，将鉴权、日志等逻辑与业务逻辑分离开，更好地实现代码重用。
这三部分的内容对于开发者来说都很有用。遵循JAX-RS规范做开发，可以确保服务器端以及客户端代码的可移植性。
李建业：我个人关注异步API这部分，主要是因为流式服务将会越来越多，那将大量需要这类支持。
InfoQ：能否为InfoQ的读者推荐一款实用的RESTful API开发框架，并说明您的推介理由。
李锟：这个问题我就不详细回答了。不同的编程语言有不同的REST开发框架，对于REST的支持程度也不同。开发RESTful&API的需求范围很广，可选择的开发框架的范围也很广。保持多样性是繁荣生态环境的基础。像Java就有支持JAX-RS规范的Jersey、RESTEasy、Restlet、Apache&CXF，和不支持JAX-RS规范的Spring&MVC等等很多框架。这些框架目前都做的不错。我对框架的选择没有倾向性。RESTful&API设计的最佳实践应该是通用的，而不是必须依赖某种特定的开发框架。
李建业：不好意思，这个我不太重视，没法推荐，不过我可以解释一下为什么对RESTful&API框架不感冒的原因。
REST作为一个架构风格，对我们的系统开发有很大影响，但是这些影响一般是针对架构（例如状态无关）或者设计（例如资源识别）上的，所以一旦涉及到具体实现，主要工作就基本结束了，此时开发框架能做的事也就只有简化编程了（相较而言，有的框架还能起到引导设计的作用），而由于RESTful会抽象动词，所以实现层面中和API规范相关的工作本来就不多，那么框架的价值就更小了。
当然，我们也不可能直接基于servlet/rakc/wsgi来开发，不过一般的编程语言都会提供一些简单的url&route/match策略，我们使用这些就足够了。另外，有些框架能帮我们生成全部的动词支持，但这也未必是好事，我一般倾向于按需实现——用到了再支持，这就更不需要太关注开发框架对RESTful的支持了。
丁雪丰：由于本人是Spring的拥护者，工作中也一直在使用Spring，所以在选择框架时会更多地倾向Spring&MVC（并不是说别的框架不好，这里有些个人主观的成份）。如果一定要选择其他框架，也要选择能够方便与Spring集成的框架。如果在项目中已经使用了Spring，那么没有什么理由不选择Spring&MVC，鉴于目前Spring在各种项目中的高出镜率，相信一般情况下都会选择Spring&MVC。
REST的成熟度模型中，第三层就是HATEOAS，Spring目前还提供了Spring&Hateoas子项目，对链接、资源等方面的支持都做了一定的增强。
马钧：我目前在实际项目中使用的是Spray，这是一个开源的&REST/HTTP&工具包和底层网络&IO&包，基于&Scala&和&Akka&构建。轻量级、异步、非堵塞、基于&actor&模式、模块化和可测试是Spray的特点。
InfoQ：HTTP2.0规范正在制定当中，您对它的期待是什么？
李锟：我的期待包括两个方面：应该做的和不应该做的。
HTTP/2.0规范应该做的：
1.与HTTP/1.1协议保持兼容。兼容的含义是说两者可以并存，客户端应用可以根据服务器端的能力，自由地选择使用HTTP/2.0还是HTTP/1.1，而且选择过程对应用来说是透明的。&
2.改进HTTP协议（作为资源的统一接口）之中操作语义表达方式的语法，提高网络传输效率。&
3.更好地模块化，这样HTTP/2.0协议的实现能够更好地模块化。应用程序可根据需要选择适当的模块，而不是要么全有、要么全无。&
4.废弃掉HTTP/1.1协议中一些很少有人用到的部分，例如采用管道（pipelining）方式发送请求。&
5.增加更多的动词，以适应除CRUD之外的其他场景。
HTTP/2.0规范不应该做的：
HTTP/2.0协议不应该把底层的数据加密机制（即SSL）作为必选项。
HTTP/2.0协议不应该背离REST架构风格的约束，尤其是要确保操作语义对于中间组件的可见性。&
在上面这两个方面，Roy&Fileidng曾经与SPDY协议设计者Mike&Belshe发生过激烈争论，详情请看：Roy&Fielding谈Google&SPDY协议
李建业：对此规范关注不多，不知道会不会有对于流的支持，目前我所知道的只有chunk方式进行简单的支持，但是真正的流需要区分数据通道和控制通道——哪怕是逻辑上的区分，这样就直接对REST风格产生了很大冲击，考虑到流式服务在未来的发展潜力，我特别期待业界在这方面有所进展。
丁雪丰：HTTP&2.0很大程度上是借鉴了Google的SPDY，就我而言，首先，希望这个规范能做到与HTTP&1.1的兼容，使用者如果只认识1.1，那么2.0能优雅“降级”；其次，希望2.0能带来更好的性能，SPDY在这方面还是有所改进的，希望HTTP&2.0能再接再厉；最后，希望这个规范能在最终定稿时附带一个最佳实践，正确引导人们合理地使用HTTP&2.0。
马钧：没研究过，估计即使出来，1.1还有很长的生命周期，不会很快被取代
参考知识库
* 以上用户言论只代表其个人观点，不代表CSDN网站的观点或立场
访问：25170次
排名：千里之外
转载：27篇
(7)(17)(4)(6)问题对人有帮助，内容完整，我也想知道答案
问题没有实际价值，缺少关键内容，没有改进余地
RT，譬如如何防止重放攻击神马的，我觉得仅仅加个access_token没什么用吧，请众神赐教，最好能举个例子，譬如微博或者twitter怎么做的，谢谢。
————————————————————————————————————————————————————————————————
补充一下，其实我就是想问问rest api怎么防重放的。。。。
来源: 101 新手上路
答案对人有帮助，有参考价值
答案没帮助，是错误的答案，答非所问
RESTFul API在安全性方面跟其它的web app没有什么区别
RESTFul只是一种架构风格，不会产生安全上的差异
你这个问题就不该把REST扯进来，重放攻击才不管是不是REST
而且你问了好大一个问题，我觉得重放攻击的实施跟具体的业务逻辑关联紧密，在没有设置具体场景的情况下，只能泛泛而谈
百度百科就有一些防御思路，你将就琢磨一下吧
答案对人有帮助，有参考价值
答案没帮助，是错误的答案，答非所问
1.《RESTful API 设计最佳实践》这本书提出有三种方案：基本的http basic，Hash Message Authentication Code (HMAC)，token auth logic，当然你也可以实现更多，比如参考：[Kerberos]: 、oauth等等，八仙过海各显神通！
2.找到适合自己的才是好的
答案对人有帮助，有参考价值
答案没帮助，是错误的答案，答非所问
推荐极简的Restful框架
开发效率比ssh高了n倍，其中resty-security是极简的权限设计，非常小巧只有10个左右class文件
关于防止重放攻击，目前主流做法，是客户端发送请求时带请求编号，服务器保存编号，当重放攻击时(只要编号规则没有被破解，一般不会出现)发出的请求请求编号应该是相同的，服务器过滤掉就行，大多数权限框架都不支持该方法，主要是需要客户端做一些处理比较麻烦
答案对人有帮助，有参考价值
答案没帮助，是错误的答案，答非所问
1、Https加密2、接口加密，参数结合时间戳加密（服务器端对比时间戳，时间戳在误差范围外过滤掉）
答案对人有帮助，有参考价值
答案没帮助，是错误的答案，答非所问
现在主流的都是用oauth2协议吧，oauth2具体可以参考：
是给rails开发的restful API加上oauth的例子，楼主可以参考。
现在主流的语言一般都有oauth2的库，应该都不难加上oauth2。
答案对人有帮助，有参考价值
答案没帮助，是错误的答案，答非所问
可以从服务器日志入手,统计一定时间段内访问超过次的用户,禁止该ip继续访问
同步到新浪微博
分享到微博？
Hi，欢迎来到 SegmentFault 技术社区！⊙▽⊙ 在这里，你可以提出编程相关的疑惑，关注感兴趣的问题，对认可的回答投赞同票；大家会帮你解决编程的问题，和你探讨技术更新，为你的回答投上赞同票。
明天提醒我
关闭理由：
删除理由：
忽略理由：
推广（招聘、广告、SEO 等）方面的内容
与已有问题重复（请编辑该提问指向已有相同问题）
答非所问，不符合答题要求
宜作评论而非答案
带有人身攻击、辱骂、仇恨等违反条款的内容
无法获得确切结果的问题
非开发直接相关的问题
非技术提问的讨论型问题
其他原因（请补充说明）
我要该，理由是：
扫扫下载 App
SegmentFault
一起探索更多未知RESTful API 设计最佳实践 - 文章 - 伯乐在线
& RESTful API 设计最佳实践
目前互联网上充斥着大量的关于RESTful API（为方便，下文中“RESTful API ”简写为“API”）如何设计的文章，然而却没有一个”万能“的设计标准：如何鉴权？API 格式如何？你的API是否应该加入版本信息？当你开始写一个app的时候，特别是后端模型部分已经写完的时候，你不得不殚精竭虑的设计和实现自己app的public API部分。因为一旦发布，对外发布的API将会很难改变。
在给SupportedFu设计API的时候，我试图以实用的角度来解决上面提到的问题。我希望可以设计出容易使用，容易部署，并且足够灵活的API，本文因此而生。
API设计的基本要求
网上的很多关于API设计的观点都十分”学院派“，它们也许更有理论基础，但是有时却和现实世界脱轨（因此我是自由派）。所以我这篇文章的目标是从实践的角度出发，给出当前网络应用的API设计最佳实践（当然，是我认为的最佳了~），如果觉得不合适，我不会遵从标准。当然作为设计的基础，几个必须的原则还是要遵守的：
当标准合理的时候遵守标准。
API应该对程序员友好，并且在浏览器地址栏容易输入。
API应该简单，直观，容易使用的同时优雅。
API应该具有足够的灵活性来支持上层ui。
API设计权衡上述几个原则。
需要强调的是：API的就是程序员的UI，和其他UI一样，你必须仔细考虑它的用户体验！
使用RESTful URLs 和action.
虽然前面我说没有一个万能的API设计标准。但确实有一个被普遍承认和遵守：RESTfu设计原则。它被Roy Felding提出（在他的”基于网络的软件架构“论文中）。而REST的核心原则是将你的API拆分为逻辑上的资源。这些资源通过http被操作（GET ,POST,PUT,DELETE）。
那么我应该如何拆分出这些资源呢？
显然从API用户的角度来看，”资源“应该是个名词。即使你的内部数据模型和资源已经有了很好的对应，API设计的时候你仍然不需要把它们一对一的都暴露出来。这里的关键是隐藏内部资源，暴露必需的外部资源。
在SupportFu里，资源是 ticket、user、group。
一旦定义好了要暴露的资源，你可以定义资源上允许的操作，以及这些操作和你的API的对应关系：
GET /tickets # 获取ticket列表
GET /tickets/12 # 查看某个具体的ticket
POST /tickets # 新建一个ticket
PUT /tickets/12 # 更新ticket 12.
DELETE /tickets/12 #删除ticekt 12
可以看出使用REST的好处在于可以充分利用http的强大实现对资源的CURD功能。而这里你只需要一个endpoint：/tickets,再没有其他什么命名规则和url规则了，cool！
这个endpoint的单数复数
一个可以遵从的规则是：虽然看起来使用复数来描述某一个资源实例看起来别扭，但是统一所有的endpoint，使用复数使得你的URL更加规整。这让API使用者更加容易理解，对开发者来说也更容易实现。
如何处理关联？关于如何处理资源之间的管理REST原则也有相关的描述：
GET /tickets/12/messages- Retrieves list of messages for ticket #12
GET /tickets/12/messages/5- Retrieves message #5 for ticket #12
POST /tickets/12/messages- Creates a new message in ticket #12
PUT /tickets/12/messages/5- Updates message #5 for ticket #12
PATCH /tickets/12/messages/5- Partially updates message #5 for ticket #12
DELETE /tickets/12/messages/5- Deletes message #5 for ticket #12
其中，如果这种关联和资源独立，那么我们可以在资源的输出表示中保存相应资源的endpoint。然后API的使用者就可以通过点击链接找到相关的资源。如果关联和资源联系紧密。资源的输出表示就应该直接保存相应资源信息。（例如这里如果message资源是独立存在的，那么上面 GET /tickets/12/messages就会返回相应message的链接；相反的如果message不独立存在，他和ticket依附存在，则上面的API调用返回直接返回message信息）
不符合CURD的操作
对这个令人困惑的问题，下面是一些解决方法：
重构你的行为action。当你的行为不需要参数的时候，你可以把active对应到activated这个资源，（更新使用patch）.
以子资源对待。例如:github上，对一个gists加星操作：PUT /gists/:id/star 并且取消星操作：DELETE /gists/:id/star.
有时候action实在没有难以和某个资源对应上例如search。那就这么办吧。我认为API的使用者对于/search这种url也不会有太大意见的（毕竟他很容易理解）。只要注意在文档中写清楚就可以了。
永远使用SSL
毫无例外，永远都要使用SSL。你的应用不知道要被谁，以及什么情况访问。有些是安全的，有些不是。使用SSL可以减少鉴权的成本：你只需要一个简单的令牌（token）就可以鉴权了，而不是每次让用户对每次请求签名。
值得注意的是：不要让非SSL的url访问重定向到SSL的url。
文档和API本身一样重要。文档应该容易找到，并且公开（把它们藏到pdf里面或者存到需要登录的地方都不太好）。文档应该有展示请求和输出的例子：或者以点击链接的方式或者通过curl的方式（请见openstack的文档）。如果有更新（特别是公开的API），应该及时更新文档。文档中应该有关于何时弃用某个API的时间表以及详情。使用邮件列表或者博客记录是好方法。
在API上加入版本信息可以有效的防止用户访问已经更新了的API，同时也能让不同主要版本之间平稳过渡。关于是否将版本信息放入url还是放入请求头有过争论：. 学术界说它应该放到header里面去，但是如果放到url里面我们就可以跨版本的访问资源了。。（参考openstack）。
strip使用的方法就很好：它的url里面有主版本信息，同时请求头俩面有子版本信息。这样在子版本变化过程中url的稳定的。变化有时是不可避免的，关键是如何管理变化。完整的文档和合理的时间表都会使得API使用者使用的更加轻松。
结果过滤，排序，搜索：
url最好越简短越好，和结果过滤，排序，搜索相关的功能都应该通过参数实现(并且也很容易实现)。
过滤：为所有提供过滤功能的接口提供统一的参数。例如：你想限制get /tickets 的返回结果:只返回那些open状态的ticket–get /tickektsstate=open这里的state就是过滤参数。
排序：和过滤一样，一个好的排序参数应该能够描述排序规则，而不业务相关。复杂的排序规则应该通过组合实现：
GET /ticketssort=-priority- Retrieves a list of tickets in descending order of priority
GET /ticketssort=-priority,created_at- Retrieves a list of tickets in descending order of priority. Within a specific priority, older tickets are ordered first
这里第二条查询中，排序规则有多个rule以逗号间隔组合而成。
搜索：有些时候简单的排序是不够的。我们可以使用搜索技术（ElasticSearch和Lucene）来实现（依旧可以作为url的参数）。
GET /ticketsq=return&state=open&sort=-priority,created_at- Retrieve the highest priority open tickets mentioning the word ‘return’
对于经常使用的搜索查询，我们可以为他们设立别名,这样会让API更加优雅。例如：
get /ticketsq=recently_closed -& get /tickets/recently_closed.
限制API返回值的域
有时候API使用者不需要所有的结果，在进行横向限制的时候（例如值返回API结果的前十项）还应该可以进行纵向限制。并且这个功能能有效的提高网络带宽使用率和速度。可以使用fields查询参数来限制返回的域例如：
GET /ticketsfields=id,subject,customer_name,updated_at&state=open&sort=-updated_at
更新和创建操作应该返回资源
PUT、POST、PATCH 操作在对资源进行操作的时候常常有一些副作用：例如created_at,updated_at 时间戳。为了防止用户多次的API调用（为了进行此次的更新操作），我们应该会返回更新的资源（updated representation.）例如：在POST操作以后，返回201 created 状态码，并且包含一个指向新资源的url作为返回头
是否需要 “HATEOAS“
网上关于是否允许用户创建新的url有很大的异议（注意不是创建资源产生的url）。为此REST制定了HATEOAS来描述了和endpoint进行交互的时候，行为应该在资源的metadata返回值里面进行定义。
（译注：作者这里认为HATEOAS还不算成熟，我也不怎么理解这段就算了，读者感兴趣可以自己去原文查看）
只提供json作为返回格式
现在开始比较一下XML和json了。XML即冗长，难以阅读，又不适合各种编程语言解析。当然XML有扩展性的优势，但是如果你只是将它来对内部资源串行化，那么他的扩展优势也发挥不出来。很多应用（youtube,twitter,box）都已经开始抛弃XML了，我也不想多费口舌。给了google上的趋势图吧：
当然如果的你使用用户里面企业用户居多，那么可能需要支持XML。如果是这样的话你还有另外一个问题：你的http请求中的media类型是应该和accept 头同步还是和url？为了方便（browser explorability）,应该是在url中(用户只要自己拼url就好了)。如果这样的话最好的方法是使用.xml或者.json的后缀。
命名方式？
是蛇形命令（下划线和小写）还是驼峰命名？如果使用json那么最好的应该是遵守JAVASCRIPT的命名方法-也就是说骆驼命名法。如果你正在使用多种语言写一个库，那么最好按照那些语言所推荐的，java，c#使用骆驼，python，ruby使用snake。
个人意见：我总觉得蛇形命令更好使一些，当然这没有什么理论的依据。有人说蛇形命名读起来更快，能达到20%，也不知道真假
默认使用pretty print格式，使用gzip
只是使用空格的返回结果从浏览器上看总是觉得很恶心(一大坨有没有？～)。当然你可以提供url上的参数来控制使用“pretty print”，但是默认开启这个选项还是更加友好。格外的传输上的损失不会太大。相反你如果忘了使用gzip那么传输效率将会大大减少，损失大大增加。想象一个用户正在debug那么默认的输出就是可读的-而不用将结果拷贝到其他什么软件中在格式化-是想起来就很爽的事，不是么？
下面是一个例子:
$ curl /users/veesahni & with-whitespace.txt
$ ruby -r json -e 'puts JSON JSON.parse(STDIN.read)' & with-whitespace.txt & without-whitespace.txt
$ gzip -c with-whitespace.txt & with-whitespace.txt.gz
$ gzip -c without-whitespace.txt & without-whitespace.txt.gz
$ curl https:///users/veesahni & with-whitespace.txt$ ruby -r json -e 'puts JSON JSON.parse(STDIN.read)' & with-whitespace.txt & without-whitespace.txt$ gzip -c with-whitespace.txt > with-whitespace.txt.gz$ gzip -c without-whitespace.txt > without-whitespace.txt.gz
输出如下：
without-whitespace.txt- 1252 bytes
with-whitespace.txt- 1369 bytes
without-whitespace.txt.gz- 496 bytes
with-whitespace.txt.gz- 509 bytes
在上面的例子中，多余的空格使得结果大小多出了8.5%（没有使用gzip），相反只多出了2.6%。据说：twitter使用gzip之后它的streaming API传输减少了80%（link:/blog/announcing-gzip-compression-streaming-APIs）.
只在需要的时候使用“envelope”
很多API象下面这样返回结果：
"data" : {
"id" : 123,
"name" : "John"
{&&"data" : {&&&&"id" : 123,&&&&"name" : "John"&&}}
理由很简单：这样做可以很容易扩展返回结果，你可以加入一些分页信息，一些数据的元信息等－这对于那些不容易访问到返回头的API使用者来说确实有用，但是随着“标准”的发展（cors和http://tools.ietf.org/html/rfc5988#page-6都开始被加入到标准中了），我个人推荐不要那么做。
何时使用envelope？
有两种情况是应该使用envelope的。如果API使用者确实无法访问返回头，或者API需要支持交叉域请求（通过jsonp）。
jsonp请求在请求的url中包含了一个callback函数参数。如果给出了这个参数，那么API应该返回200，并且把真正的状态码放到返回值里面（包装在信封里），例如：
JavaScript
callback_function({
status_code: 200,
next_page: "https://..",
response: {
... actual JSON response body ...
callback_function({&&status_code: 200,&&next_page: "https://..",&&response: {&&&&... actual JSON response body ... &&}})
同样为了支持无法方法返回头的API使用者，可以允许envelope=true这样的参数。
在post,put,patch上使用json作为输入
如果你认同我上面说的，那么你应该决定使用json作为所有的API输出格式，那么我们接下来考虑考虑API的输入数据格式。
很多的API使用url编码格式：就像是url查询参数的格式一样：单纯的键值对。这种方法简单有效，但是也有自己的问题：它没有数据类型的概念。这使得程序不得不根据字符串解析出布尔和整数,而且还没有层次结构–虽然有一些关于层次结构信息的约定存在可是和本身就支持层次结构的json比较一下还是不很好用。
当然如果API本身就很简单，那么使用url格式的输入没什么问题。但对于复杂的API你应该使用json。或者干脆统一使用json。
注意使用json传输的时候，要求请求头里面加入：Content-Type：application/json.，否则抛出415异常（unsupported media type）。
分页数据可以放到“信封”里面，但随着标准的改进，现在我推荐将分页信息放到link header里面：http://tools.ietf.org/html/rfc5988#page-6。
使用link header的API应该返回一系列组合好了的url而不是让用户自己再去拼。这点在基于游标的分页中尤为重要。例如下面，来自github的文档
Link: &/user/repos?page=3&per_page=100&; rel="next",
&/user/repos?page=50&per_page=100&; rel="last"
Link: &https:///user/repos?page=3&per_page=100&; rel="next", &https:///user/repos?page=50&per_page=100&; rel="last"
自动加载相关的资源
很多时候，自动加载相关资源非常有用，可以很大的提高效率。但是这却。为了如此，我们可以在url中添加参数：embed（或者expend）。embed可以是一个逗号分隔的串，例如：
GET /ticket/12embed=customer.name,assigned_user
GET /ticket/12embed=customer.name,assigned_user
对应的API返回值如下：
"id" : 12,
"subject" : "I have a question!",
"summary" : "Hi, ....",
"customer" : {
"name" : "Bob"
assigned_user: {
"id" : 42,
"name" : "Jim",
123456789101112
{&&"id" : 12,&&"subject" : "I have a question!",&&"summary" : "Hi, ....",&&"customer" : {&&&&"name" : "Bob"&&},&&assigned_user: {&& "id" : 42,&& "name" : "Jim",&&}}
值得提醒的是，这个功能有时候会很复杂，并且可能导致。
重写HTTP方法
有的客户端只能发出简单的GET 和POST请求。为了照顾他们，我们可以重写HTTP请求。这里没有什么标准，但是一个普遍的方式是接受X-HTTP-Method-Override请求头。
为了避免请求泛滥，给API设置速度限制很重要。为此
引入了HTTP状态码。加入速度设置之后，应该提示用户，至于如何提示标准上没有说明，不过流行的方法是使用HTTP的返回头。
下面是几个必须的返回头（依照twitter的命名规则）：
X-Rate-Limit-Limit :当前时间段允许的并发请求数
X-Rate-Limit-Remaining:当前时间段保留的请求数。
X-Rate-Limit-Reset:当前时间段剩余秒数
为什么使用当前时间段剩余秒数而不是时间戳？
时间戳保存的信息很多，但是也包含了很多不必要的信息，用户只需要知道还剩几秒就可以再发请求了这样也避免了。
有些API使用UNIX格式时间戳，我建议不要那么干。为什么？HTTP 已经规定了使用
鉴权 Authentication
restful API是无状态的也就是说用户请求的鉴权和cookie以及session无关，每一次请求都应该包含鉴权证明。
通过使用ssl我们可以不用每次都提供用户名和密码：我们可以给用户返回一个随机产生的token。这样可以极大的方便使用浏览器访问API的用户。这种方法适用于用户可以首先通过一次用户名-密码的验证并得到token，并且可以拷贝返回的token到以后的请求中。如果不方便，可以使用OAuth 2来进行token的安全传输。
支持jsonp的API需要额外的鉴权方法，因为jsonp请求无法发送普通的credential。这种情况下可以在查询url中添加参数：access_token。注意使用url参数的问题是：目前大部分的网络服务器都会讲query参数保存到服务器日志中，这可能会成为大的安全风险。
注意上面说到的只是三种传输token的方法，实际传输的token可能是一样的。
HTTP提供了自带的缓存框架。你需要做的是在返回的时候加入一些返回头信息，在接受输入的时候加入输入验证。基本两种方法：
ETag：当生成请求的时候，在HTTP头里面加入ETag，其中包含请求的校验和和哈希值，这个值和在输入变化的时候也应该变化。如果输入的HTTP请求包含IF-NONE-MATCH头以及一个ETag值，那么API应该返回304 not modified状态码，而不是常规的输出结果。
Last-Modified：和etag一样，只是多了一个时间戳。返回头里的Last-Modified：包含了
时间戳，它和IF-MODIFIED-SINCE一致。HTTP规范里面有三种date格式，服务器应该都能处理。
就像html错误页面能够显示错误信息一样，API 也应该能返回可读的错误信息–它应该和一般的资源格式一致。API应该始终返回相应的状态码，以反映服务器或者请求的状态。API的错误码可以分为两部分，400系列和500系列，400系列表明客户端错误：如错误的请求格式等。500系列表示服务器错误。API应该至少将所有的400系列的错误以json形式返回。如果可能500系列的错误也应该如此。json格式的错误应该包含以下信息：一个有用的错误信息，一个唯一的错误码，以及任何可能的详细错误描述。如下：
"code" : 1234,
"message" : "Something bad happened :-(",
"description" : "More details about the error here"
{&&"code" : 1234,&&"message" : "Something bad happened :-(",&&"description" : "More details about the error here"}
对PUT,POST,PATCH的输入的校验也应该返回相应的错误信息，例如：
"code" : 1024,
"message" : "Validation Failed",
"errors" : [
"code" : 5432,
"field" : "first_name",
"message" : "First name cannot have fancy characters"
"code" : 5622,
"field" : "password",
"message" : "Password cannot be blank"
12345678910111213141516
{&&"code" : 1024,&&"message" : "Validation Failed",&&"errors" : [&&&&{&&&&&&"code" : 5432,&&&&&&"field" : "first_name",&&&&&&"message" : "First name cannot have fancy characters"&&&&},&&&&{&&&&&& "code" : 5622,&&&&&& "field" : "password",&&&&&& "message" : "Password cannot be blank"&&&&}&&]}
HTTP 状态码
- 成功返回状态，对应，GET,PUT,PATCH,DELETE.
201 created
- 成功创建。
304 not modified
- HTTP缓存有效。
400 bad request
- 请求格式错误。
401 unauthorized
- 未授权。
403 forbidden
- 鉴权成功，但是该用户没有权限。
404 not found - 请求的资源不存在
405 method not allowed - 该http方法不被允许。
410 gone - 这个url对应的资源现在不可用。
415 unsupported media type - 请求类型错误。
422 unprocessable entity - 校验错误时用。
429 too many request - 请求过多。
123456789101112
- 成功返回状态，对应，GET,PUT,PATCH,DELETE. 201 created
- 成功创建。 304 not modified
- HTTP缓存有效。 400 bad request
- 请求格式错误。 401 unauthorized
- 未授权。 403 forbidden
- 鉴权成功，但是该用户没有权限。 404 not found - 请求的资源不存在 405 method not allowed - 该http方法不被允许。 410 gone - 这个url对应的资源现在不可用。 415 unsupported media type - 请求类型错误。 422 unprocessable entity - 校验错误时用。 429 too many request - 请求过多。
关于作者：
可能感兴趣的话题
注意使用json传输的时候，要求请求头里面加入：Content-Type：applicatin/json.否则抛出415异常（unsupported media type）
applicatin -& application
关于伯乐在线博客
在这个信息爆炸的时代，人们已然被大量、快速并且简短的信息所包围。然而，我们相信：过多“快餐”式的阅读只会令人“虚胖”，缺乏实质的内涵。伯乐在线内容团队正试图以我们微薄的力量，把优秀的原创文章和译文分享给读者，为“快餐”添加一些“营养”元素。
新浪微博：
推荐微信号
（加好友请注明来意）
– 好的话题、有启发的回复、值得信赖的圈子
– 分享和发现有价值的内容与观点
– 为IT单身男女服务的征婚传播平台
– 优秀的工具资源导航
– 翻译传播优秀的外文文章
– 国内外的精选文章
– UI,网页，交互和用户体验
– 专注iOS技术分享
– 专注Android技术分享
– JavaScript, HTML5, CSS
– 专注Java技术分享
– 专注Python技术分享
& 2017 伯乐在线