在线查看地址：https://files-cdn.cnblogs.com/files/bjlhx/web-api-design-ebook-2012-03.pdf
下载地址：https://files.cnblogs.com/files/bjlhx/web-api-design-ebook-2012-03.pdf
一、概述
因为REST是一种架构风格而不是严格的标准，所以它可以灵活地实现。由于这种灵活性和结构自由度，对设计最佳实践也有很大的差异。
API设计的成功与否取决于开发人员如何快速加速并开始使用API获得成功。
以下设计仅仅是一些经验的总结，不是一些教条。
从“从外到内”的角度来看待API设计。 这意味着我们开始问 - 我们试图用API实现什么？API的工作是让开发人员尽可能成功。 API的方向是从应用程序开发人员的角度考虑设计选择。
为什么？ 看看下面的价值链 - 应用程序开发人员是其中的关键整个API策略。 制作API时的主要设计原则应该是最大化开发人员的工作效率 这就是我们所说的实用REST。
实用REST是一个设计问题你必须正确设计，因为设计会传达出某些东西用过的。 问题变成了 - 为应用程序带来最佳效益的设计是什么开发者？开发人员的观点是所有具体技巧和最佳指导原则我们编写的实践。
二、名词优先，禁止动词
RESTful设计中的首要原则是：简单易懂。
1、保持您的基本网址简单直观
2、将动词保留在基本URL之外
3、使用HTTP谓词对集合和元素进行操作。
三、复数名词和实际名称
具体名称比抽象更好。总之，直观的API使用复数而不是单数名词，而不是抽象名称。
四、简化关联，复杂属性放置在？后面
简化关联：/resource/identifier/resource.
复杂属性：GET /dogs?color=red&state=running&location=park
五、处理错误
参看比较热点的几个站点错误处理
Facebook HTTP Status Code: 200 {"type" : "OauthException", "message":"(#803) Some of the aliases you requested do not exist: foo.bar"} Twilio HTTP Status Code: 401 {"status" : "401", "message":"Authenticate","code": 20003, "more info": "http://www.twilio.com/docs/errors/20003"} SimpleGeo HTTP Status Code: 401 {"code" : 401, "message": "Authentication Required"}
Twilior设计是比较好的
一些最佳实践
1、使用HTTP状态代码
使用HTTP状态代码并尝试将它们干净地映射到相关的基于标准的代码。 有超过70个HTTP状态代码。 但是，大多数开发人员并没有全部记住70。 因此，如果您不推荐选择不常见的状态代码。
参看上述站点http状态码使用：
Google GData 200 201 304 400 401 403 404 409 410 500 Netflix 200 201 304 400 401 403 404 412 500 Digg 200 400 401 403 404 410 500 503
2、您应该为API使用多少状态代码？ 在应用和API之间的交互中实际上只有3个结果：
成功：200，ok
客户端错误，400，Bad request
服务器错误，500，Internal Server Error
注意：推荐使用以上，但是最好不要超过8个，而且对应的Http响应码需要与之对应，更多wiki http status,百科地址
备选
201 - Created 304 - Not Modified 404 – Not Found 401 - Unauthorized 403 - Forbidden
3、确保payload返回消息尽可能详细，推荐如下
{ "developerMessage": "Verbose, plain language description of the problem for the app developer with hints about how to fix it.", "moreInfo": "http://www.twilio.com/docs/errors/20003", "status": "401", "message": "Authenticate", "code": 20003 }
六、版本控制
示例
Twilio /2010-04-01/Accounts/
salesforce.com /services/data/v20.0/sobjects/Account
Facebook ?v=1.0
1、如何使用REST以实用的方式考虑版本号？
从不在没有版本的情况下发布API。 使版本成为强制性的。 指定带有'v'前缀的版本。 将其一直移动到URL中的左侧，使其具有最高范围（例如/ v1 / dogs）。
使用简单的序数。 不要像v1.2那样使用点符号，因为它意味着版本控制的粒度与API不兼容 - 它是一个接口而不是实现。 坚持使用v1，v2等。
你应该维护多少个版本？ 至少维护一个版本。 您应该维护多长时间？ 在淘汰版本之前，给开发人员至少一个周期做出反应。 有时那是6个月; 有时它是2年。 这取决于您的开发人员的开发平台，应用程序类型和应用程序用户。 例如，移动应用程序比Web应用程序需要更长的时间。
2、版本和格式应该放在URL还是header中
遵循的简单规则：如果它更改了您编写的逻辑以处理响应，请将其放在URL中，以便您可以轻松查看。如果它没有更改每个响应的逻辑，例如OAuth信息，请将其放在标题中。
七、分页，响应，部分响应
1、部分响应
部分响应允许您为开发人员提供他们所需的信息。Google开创了部分响应的概念。
LinkedIn /people:(id,first-name,last-name,industry) // LinkedIn使用这种简洁的语法进行部分选择:( ...）语法不是不言自明的。 此外，开发人员很难使用搜索引擎对其含义进行逆向工程。 Facebook /joe.smith/friends?fields=id,name,picture Google ?fields=title,media:group(media:thumbnail)
谷歌和Facebook有类似的方法，效果很好。 它们每个都有一个名为fields的可选参数，之后您将放置要返回的字段的名称。 正如您在此示例中所看到的，您还可以将子对象放入响应中以从其他资源中提取其他信息。
在逗号分隔的列表中添加可选字段Google方法非常有效。
推荐使用：谷歌和Facebook方式
2、分页【确保分页对象在数据库中易用】
Facebook - offset 50 and limit 25 Twitter - page 3 and rpp 25 (records per page) LinkedIn - start 50 and count 25
推荐使用： limit and offset 或者使用pagehelper的page对象，分页必须提供默认值，在不传输参数情况下：(limit=10&offset=0)
建议在每个分页响应中包含元数据，这些响应分配给开发人员可用的记录总数。
3、那些不涉及资源的回复
将一种货币转换为另一种货币。没有涉及从数据库返回的资源。在这些情况下：使用动词而不是名词例如，将100欧元转换为中国日元的API：/ convert？from = EUR＆to = CNY＆amount = 100在API文档中明确指出这些“非资源”方案是不同的。简单地分开一部分文档，清楚地表明你在这种情况下使用动词 - 采取一些动作来生成或计算响应，而不是直接返回资源。
4、需要支持多种数据响应格式
示例
Google Data ?alt=json Foursquare /venue.json Digg* Accept: application/json ?type=json
推荐：使用JSON做默认格式， JSON是我们对通用语言最接近的东西。即使后端是用Ruby on Rails，PHP，Java，Python等构建的，大多数项目也可能会触及前端的JavaScript。它还具有简洁的优点 - 比XML简洁。
5、属性名称
支持多种格式并使用JSON作为默认格式。
示例
Twitter "created_at": "Thu Nov 03 05:19;38 +0000 2011" Bing "DateTime": "2011-10-29T09:35:00Z" Foursquare "createdAt": 1320296464
推荐使用：小驼峰方式，遵循命名属性的JavaScript约定，比较符合javascript调用
以下是反例
var myObject = JSON.parse(response); timing = myObject.created_at; timing - myObject.DateTime;
八、搜索
简单搜索：虽然简单搜索可以建模为资源丰富的API（例如，dog /？q = red），但跨多个资源的更复杂搜索需要不同的设计。 如果你在结果没有从数据库返回资源时读到关于使用动词而不是名词的话题，这听起来很熟悉 - 结果是一些动作或计算。 如果您想跨资源进行全局搜索，建议您按照Google模式进行操作：
Global search /search?q=fluffy+fur Scoped search /owners/5678/dogs?q=fluffy+fur Formatted results /search.xml?q=fluffy+fur
九、在一个子域中请求
示例：
//facebook graph.facebook.com api.facebook.com //Foursquare has one API. api.foursquare.com //Twitter has three APIs; two of them focused on search and streaming. stream.twitter.com api.twitter.com search.twitter.com
针对开发者
developers.facebook.com
developers.foursquare.com
dev.twitter.com