RESTful&API&设计指南
网络应用程序，分为前端和后端两个部分。当前的发展趋势，就是前端设备层出不穷（手机、平板、桌面电脑、其他专用设备......）。
因此，必须有一种统一的机制，方便不同的前端设备与后端进行通信。这导致API构架的流行，甚至出现的设计思想。是目前比较成熟的一套互联网应用程序的API设计理论。我以前写过一篇，探讨如何理解这个概念。
今天，我将介绍RESTful
API的设计细节，探讨如何设计一套合理、好用的API。我的主要参考资料是这篇。
API与用户的通信协议，总是使用。
应该尽量将API部署在专用域名之下。
https://api.example.com
如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。
https://example.org/api/
三、版本（Versioning）
应该将API的版本号放入URL。
https://api.example.com/v1/
另一种做法是，将版本号放在HTTP头信息中，但不如放入URL方便和直观。
四、路径（Endpoint）
路径又称"终点"（endpoint），表示API的具体网址。
在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。
举例来说，有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。
/v1/animals
/v1/employees
五、HTTP动词
对于资源的具体操作类型，由HTTP动词表示。
常用的HTTP动词有下面五个（括号里是对应的SQL命令）。
GET（SELECT）：从服务器取出资源（一项或多项）。
POST（CREATE）：在服务器新建一个资源。
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
DELETE（DELETE）：从服务器删除资源。
还有两个不常用的HTTP动词。
HEAD：获取资源的元数据。
OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。
下面是一些例子。
/zoos：列出所有动物园
/zoos：新建一个动物园
/zoos/ID：获取某个指定动物园的信息
/zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）
/zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）
/zoos/ID：删除某个动物园
/zoos/ID/animals：列出某个指定动物园的所有动物
/zoos/ID/animals/ID：删除某个指定动物园的指定动物
六、过滤信息（Filtering）
如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。
下面是一些常见的参数。
?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件
参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。比如，GET
/zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。
七、状态码（Status
服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）。
[GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
201 CREATED -
[POST/PUT/PATCH]：用户新建或修改数据成功。
204 NO CONTENT
- [DELETE]：用户删除数据成功。
400 INVALID
[POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。。
404 NOT FOUND -
[*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
500 INTERNAL
SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。
状态码的完全列表参见。
八、错误处理（Error
handling）
如果状态码是4xx，就应该向用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值即可。
error: "Invalid API key"
九、返回结果
针对不同操作，服务器向用户返回的结果应该符合以下规范。
/collection：返回资源对象的列表（数组）
/collection/resource：返回单个资源对象
/collection：返回新生成的资源对象
/collection/resource：返回完整的资源对象
/collection/resource：返回完整的资源对象
/collection/resource：返回一个空文档
十、Hypermedia
API最好做到Hypermedia，即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么。
比如，当用户向的根目录发出请求，会得到这样一个文档。
{"link": {
"collection ",
"title": "List of zoos",
"application/vnd.yourformat+json"
上面代码表示，文档中有一个link属性，用户读取这个属性就知道下一步该调用什么API了。rel表示这个API与当前网址的关系（collection关系，并给出该collection的网址），href表示API的路径，title表示API的标题，type表示返回类型。
Hypermedia
API的设计被称为。Github的API就是这种设计，访问会得到一个所有可用API的网址列表。
"current_user_url": "",
"authorizations_url": "",
从上面可以看到，如果想获取当前用户的信息，应该去访问，然后就得到了下面结果。
"message": "Requires authentication",
"documentation_url": ""
上面代码表示，服务器给出了提示信息，以及文档的网址。
十一、其他
（1）API的身份认证应该使用框架。
（2）服务器返回的数据格式，应该尽量使用JSON，避免使用XML。
版权声明：自由转载-非商用-非衍生-保持署名（）
发表日期：&日
更多内容：&&&&
付费支持：
社交媒体：，
Feed订阅：&
Git是目前最流行的版本管理系统，学会Git几乎成了开发者的必备技能。
OAuth是一个关于授权（authorization）的开放网络标准，在全世界得到广泛应用，目前的版本是2.0版。
开发网站的时候，常常需要自己配置Linux服务器。
现在，我很少写介绍CSS的文章，因为感觉网站开发的关键还是在服务器端。
留言（34条）
fallingwine&说：
"服务器返回的数据格式，应该使用JSON，不应使用XML"
存疑，返回某种自描述类的文本类数据即可，貌似没有规定不应使用XML；这与SOAP的rpc风格没有关联，两码事。
allenwest&说：
如果批量获取指定ID的一堆Zoo，按理应该用GET，但是由于ID列表可能会很长，这样会导致url过长；如果放在HTTP
Content里面，但通常只有POST这些才支持，这样又不符合HTTP动词语义。请问如何破解？
API还必须易于测试，能让用户在页面测试API，看到发送和接收的结果。
阮一峰&说：
@fallingwine：
谢谢指出，改了一下。某些场合，确实不得不使用XML。
nebula&说：
引用allenwest的发言：
如果批量获取指定ID的一堆Zoo，按理应该用GET，但是由于ID列表可能会很长，这样会导致url过长；如果放在HTTP
Content里面，但通常只有POST这些才支持，这样又不符合HTTP动词语义。请问如何破解？
url过长有什么问题？
不会是担心浏览器地址栏里的url长度吧？
hoyin&说：
這個整理得很好，讚呀。
如果 發生錯誤時，
只是拋出Status Code 真的好嗎？
如果想回應 錯誤的原因， 例如： 此日期不正確 ，之類
hoyin&说：
不好意思，忘記了可以更改Response
{"status":"XXX","message":"XXX"}
有关搜索的 API
设计没有提到，是 search?q=?吗？
“理解RESTful架构”这篇文章提到“另一个设计误区，就是在URI中加入版本号”，不是跟上面提到的第三点矛盾了吗？
jiang&说：
?sortby=name&order=asc
上面这种方式比较直观，如果用urlrewriter方式也不错，/sortby/name/order/asc，这样似乎又不符合一个url一个资源的规范
一个对象时，对象的内容是怎么放到POST参数里面呢？
是把对象转成一个json，放在一个参数里面。
还是把对象的每个字段当初一个参数？
引用Yhzhtk的发言：
一个对象时，对象的内容是怎么放到POST参数里面呢？
是把对象转成一个json，放在一个参数里面。
还是把对象的每个字段当初一个参数？
转成json放到request
body里面。
目前公司也从WCF 向API
方面转移，定义与LZ雷同...
我一般是给 web
app使用，但是浏览器对 PUT 这类支持不好，这个操作放到 URL 里合适吗？怎么处理比较好呢？
引用廖雪峰的发言：
API还必须易于测试，能让用户在页面测试API，看到发送和接收的结果。
开发人员一般都是chrome
或 firefox加插件调试
现在移动开发都是用api去调用数据，web也可以一起共用，节约开发成本。
引用Fengz的发言：
我一般是给 web
app使用，但是浏览器对 PUT 这类支持不好，这个操作放到 URL 里合适吗？怎么处理比较好呢？
对PUT这类的操作也一直是和你有着同样的困惑。
其实这只是一个推荐规范,
为了解决一些浏览器的HTTP方法的兼容问题, 还有GET URL超长的问题, 感觉可以变通为, 把HTTP方法名称也放入URI中,
/PUT/zoos/ID
/DELETE/zoos/ID
过长的参数可以自动使用POST方法来发送
蔚蓝海岸&说：
用POST，《RESTful
Web Services Cookbook》上有说过。
对于PUT和POST的用法，这篇文章和《RESTful
Web Services Cookbook》上推荐的做法不一致。
Cookbook上的做法是如果用户可以决定新创建资源的URL，那么就用PUT，否则用POST。
以及，如果不仅仅是单纯的创建一个资源，类似复杂的工厂方法（会连带创建相关的其他复杂类属性），也用POST。
引用j.w的发言：
开发人员一般都是chrome 或 firefox加插件调试
推荐Fiddler
这里有一个讲 rest api 的ppt,时代不错，有兴趣的同学可以看一下
略蛋疼，跨域的更新操作怎么破？
fromoon&说：
引用andrewyang的发言：
“理解RESTful架构”这篇文章提到“另一个设计误区，就是在URI中加入版本号”，不是跟上面提到的第三点矛盾了吗？
同问。。。
引用fromoon的发言：
同问。。。
“理解RESTful架构”的评论里也有关于“版本”讨论，这也许和个人观点有关，我是觉得是可以的。有人在/questions/972226/how-to-version-rest-uris讨论哪种加版本号的方式更好。
fakir&说：
你好 谢谢您的文章
我在我们系统中也使用这种架构 想问一下您 如果返回的数据量比较大的结构化数据 使用哪种方式速度上有优势
引用allenwest的发言：
如果批量獲取指定ID的一堆Zoo，按理應該用GET，但是由於ID列表可能會很長，這樣會導致url過長；如果放在HTTP
Content裡面，但通常只有POST這些才支持，這樣又不符合HTTP動詞語義。請問如何破解？
若你使用的是
PHP，可以透過&&來解決
引用allenwest的发言：
如果批量获取指定ID的一堆Zoo，按理应该用GET，但是由于ID列表可能会很长，这样会导致url过长；如果放在HTTP
Content里面，但通常只有POST这些才支持，这样又不符合HTTP动词语义。请问如何破解？
获取一堆的Zoo，你会经常发一堆的ID去查找吗？
我觉得获取列表往往只是发几个过滤条件，或者通过不同的endpoint，就足够了
sapwood&说：
版本应该在HTTP头中把.我一直认为Rest思想,其实就是HTTP协议的设计初衷.既然HTTP协议本身设计了版本,就应该走协议本身.而不是在协议上扩展.
你还记得你2007写的绕过gfw吗？
请教你：使用p2p技术能否把gfw打成一个千疮百孔的筛子,让其变成一个没有用的马其诺防线？
越来越受不了被人禁言和国内媒介的噤若寒蝉，特别是最近的事件，假期结束所有新闻平静沉默的吓人。
12年刚知道
BitCoin时被它的去中心技术所叹服。于是在想如果媒介或沟通也能去中心化，或者每个人都是一个中心，那么“擒贼先擒王”的办法再也无法控制每个单个个体。
A：去中心沟通工具
（1）：做一个沟通工具，之间只能通过p2p链接。
（2）：数据加密、源码开放。以BitCoin的方式认证源码。任何人都可以使用任何语言编写工具，但只能被认证通过的才可以进行沟通。防止间谍工具（代码）。
（3）：p2p自我发现（嗅探）--每个终端开启后，可以自动嗅探到最近的其它终端，最终达到全网互联。
另：也可以使用初始其它p2p链接。即：一个p2p最终可以初始保存多个（如：1000+）其它p2p地址（如：至少有一个最近的，一个外省的，一个国内的，一个国外的）。相当于多服务器（多中心）。
B：去中心“服务器”
媒介（如：网易）只要服务器在国内或者公司在国内就不可能不受制约（断域名、断Ip、断人）。如果有一个服务器是存在全网（并不位于某一具体机器），那么如果在此服务器上部署的服务是不是就不受任何人控制。
（1）：根据现在流行的大数据原理（所有结点构成整个分布式服务器，每个结点都可以充当中央结点）组建全网结点。
（2）：每个具体用户贡献一部分cpu和内存、硬盘充当结点。
C：去中心“搜索引擎”
（1）：同上，也是去中心“服务器”实现的基础。
kwk1024&说：
引用allenwest的发言：
如果批量获取指定ID的一堆Zoo，按理应该用GET，但是由于ID列表可能会很长，这样会导致url过长；如果放在HTTP
Content里面，但通常只有POST这些才支持，这样又不符合HTTP动词语义。请问如何破解？
url的长度在http协议中中没有限制，只是在浏览器中有限制
WKPlus&说：
引用AriesDevil的发言：
有关搜索的 API
设计没有提到，是 search?q=?吗？
同有点疑惑，如果按博主说的api中不能出现动词，那就不能用search了？
《理解RESTful架构》中有一段：另一个设计误区，就是在URI中加入版本号。而本文第3条又说：应该将API的版本号放入URL。两者相互冲突了。我觉得版本号不让人URL更合适一些。
bobby&说：
.Net的WebAPI
还不能http跨域调用. AJAX使用JSONP访问是只有GET请求. 怎么扩展?
/blog/2014/05/restful_api.html
已投稿到：
以上网友发言只代表其个人观点，不代表新浪网的观点或立场。Freenom – 免费提供.tk/.ml/.cf三种域名，提供经销商API - ★ 免费域名、DNS、代里 -
免费国外空间,国外免费空间, 免费域名,免费PHP空间,免费空间论坛
帖子906&积分5384&金钱762 &在线时间666 小时&注册时间&最后登录&
Freenom – 免费提供.tk/.ml/.cf三种域名，提供经销商API
Freenom将会免费提供.tk/.ml/.cf三种域名，其中.tk可能是已经开放了的，.ml和.cf则将在7月15日正式开放注册。还有~根据注册协议的话，自由注册表会免费提供经销商资格也就是和tk域名一下.cf和.ml都将会有经销商API提供，你们可以自由应用~
本贴隐藏内容，需登录、回复后，即可浏览!
注册方法参考
来自：推送：
帖子71&积分333&金钱72 &在线时间35 小时&注册时间&最后登录&
&a href='' target=_blank&&/a&
帖子7&积分15&金钱6 &在线时间0 小时&注册时间&最后登录&
这和TK一样，百度不会收录的！最多收录首页
帖子113&积分328&金钱113 &在线时间16 小时&注册时间&最后登录&
看看学习下啊
帖子25&积分66&金钱24 &在线时间3 小时&注册时间&最后登录&
帖子8627&积分26886&金钱8371 &在线时间1853 小时&注册时间&最后登录&
呀& & 三种。。。。。
这个都得去试试。
★ 11月开空间新规则，百度GG收录百贴：
★ 本站转型：推荐免费空间，收集免费空间，免费空间测试，并提供原创申请教程。
★ 免备案空间，免费空间，免费国外空间，国外免费空间，免费美国空间
★ 我们是一群辛勤的小站站长，我们需要团结，我们需要共同进步！！！！
★ 达要求开空间，论坛发申请贴后，请加QQ：&&(一般在线、有Q必回)
帖子534&积分2249&金钱870 &在线时间134 小时&注册时间&最后登录&
API可以玩玩
帖子28&积分104&金钱29 &在线时间9 小时&注册时间&最后登录&
帖子240&积分1540&金钱240 &在线时间208 小时&注册时间&最后登录&
dddddddddddddddddddddd
帖子174&积分799&金钱173 &在线时间83 小时&注册时间&最后登录&
..................................
帖子109&积分472&金钱108 &在线时间51 小时&注册时间&最后登录&
支持~~~~~~~~~~~
帖子98&积分217&金钱68 &在线时间15 小时&注册时间&最后登录&
帖子55&积分228&金钱54 &在线时间23 小时&注册时间&最后登录&
按时打算的撒旦
帖子782&积分3111&金钱791 &在线时间302 小时&注册时间&最后登录&
试试其他2个
帖子8&积分15&金钱7 &在线时间0 小时&注册时间&最后登录&
有免费的吗？
帖子3&积分5&金钱2 &在线时间0 小时&注册时间&最后登录&
canguanxia
帖子8627&积分26886&金钱8371 &在线时间1853 小时&注册时间&最后登录&
& & 呵&&难道是又增加了个 ga&&么，
下拉有三个可选了。。& & 不过，现在都看不到免费的。得$10一年
还本想多搞点做一批…………
★ 11月开空间新规则，百度GG收录百贴：
★ 本站转型：推荐免费空间，收集免费空间，免费空间测试，并提供原创申请教程。
★ 免备案空间，免费空间，免费国外空间，国外免费空间，免费美国空间
★ 我们是一群辛勤的小站站长，我们需要团结，我们需要共同进步！！！！
★ 达要求开空间，论坛发申请贴后，请加QQ：&&(一般在线、有Q必回)
帖子12&积分35&金钱11 &在线时间2 小时&注册时间&最后登录&
PayPalPayPalPayPal
帖子162&积分4033&金钱13 &在线时间754 小时&注册时间&最后登录&
PayPalPayPalPayPal
帖子906&积分5384&金钱762 &在线时间666 小时&注册时间&最后登录&
& &反正百度不能收录~~
[通过 QQ、MSN 分享给朋友]domainshare_phplib_v100 TK免费域名接口API，适合用于PHP. WEB(ASP,PHP,...) 238万源代码下载-
&文件名称: domainshare_phplib_v100
& & & & &&]
&&所属分类:
&&开发工具: PHP
&&文件大小: 5 KB
&&上传时间:
&&下载次数: 0
&&提 供 者:
&详细说明：TK免费域名接口API，适合用于PHP.-TK free domain interface API, suitable for PHP.
文件列表(点击判断是否您需要的文件，如果是垃圾请在下面评价投诉):
&&domainshare_phplib_v100\disclaimer.txt&&.......................\domainshare.php&&.......................\example.php&&.......................\support.txt
&输入关键字，在本站238万海量源码库中尽情搜索：