Web API 设计最佳实践

最近自己需要做Web API 服务，看了下这份文档，结合自己理解简单做了下总结，供参考：

英文原文下载：api-design-ebook-2012-03.pdf

1. 目标要明确。
   
   用Web API我们是要达到一个什么目的？API的主要职责在于为开发者提供服务，提高开发效率，设计过程中始终应该思考如何能为开发者带来更多益处。因此，在设计API时应多以开发者的视角来思考问题。这个基本思想可以称之为“pragamatic REST”。
2. 用名词而不是动词，URL应该简单明了。
   
   对于一个特定的资源，一般基础URL为两个。例如：获取所有的狗狗 /dogs ；获取指定的狗狗 /dogs/1234 。不要在URL中引用动词，这样会造成URL繁多，一致性差，不便于开发者使用。
3. 用HTTP方法来对资源集合及资源集合中特定资源进行操作。
   
   利用POST/GET/PUT/DELETE来对资源进行操作，对应我们通常说的增删改查（CRUD：Create-Read-Update-Delete）。
4. 用复数名词和有意义的名称。
   
   用单数名词还是复数名词没有哪个好与不好，总之应该保持一致性，不要混用。推荐使用复数名词。另外，应该使用有具体含义的名称，而不是抽象意义的名称。比如抽象的 /items ，具体的 /videos 。但这样有可能会造成资源类别过多，一般需控制在12到24之间。
5. 简化资源之间的关系，用“？”传参来英寸参数的复杂性。
   
   比如获取某一位主人的狗狗：GET /owners/1234/dogs 。这样关系如果更复杂会造成URL级别过深，一般不要在一个URL中嵌套过多的关系层，应该分开请求处理。如果参数很多，可在基础URL上用“？”来传参，例如： GET /dogs?color=red&state=running&location=park 。
6. 异常和错误处理
   
   对于开发者来说，API只是一个接口，其内部实现对于开发者是透明的。所以良好的异常和错误提示信息是非常重要的，否则出现错误只会让开发者无从下手。 下面是一些实例：
   
   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 "}
   
   一些最佳实践：1.用HTTP 状态码来表明信息。状态码有很多，但总结可归类为3种 200 - OK ；400 - Bad Request ；500 - Internal Server Error ，分别对应正常/客户端错误/服务端错误3类情况。具体可以根据实际情况自己去分类。2.返回错误的文本信息，即开发者可以直接读懂的信息，越详细越好，最好还可以给出解决问题的参考链接。
7. 关于版本控制
   
   不要release没有版本标识的API，开发者发起请求时应强制要求提供版本标识（也可使用默认版本的形式）。版本号包含在请求URL中，v开头后接具体的版本号，如 /v1/dogs 。版本发布不要出现如v1.2版之类格式，以v1，v2，v3......发布。至少维护一个版本，且应该参照开发者的实际情况确定版本发布周期。
8. 分页和部分请求
   
   例如只请求某一资源的某一部分信息，Google的做法 /dogs?fields=name,color,location ，逗号分隔，明确指定请求域。跟sql中select查询类似，一般为了提高性能，应该少用 select * 。对于分页数据请求，可以模仿数据库sql语句的做法，如 /dogs?limit=25&offset=50 。另外，最好返回数据元信息（metadata info），比如返回了多少条记录。应该提供参数的默认值，具体的默认值根据实际系统确定。
9. 对于不返回资源的处理
   
   这种情况一般指那种只是简单做下运算或是转换的情况，例如 /convert?from=EUR&to=CNY&amount=100 。对于这类情况应该在文档中单独列出说明，用到了动词:)。
10. 支持多种数据返回格式
    
    如 ?type=json 。目前json格式比较流行，且方便处理，可以作为默认的数据返回格式。
11. 对象属性的命名。属性名命名规则最好遵循JS的命名规则。
12. 关于搜索。建议遵循google的格式。例如全局搜索 /search?q=fluffy+fur 区域搜索 /owners/1234/dogs?q=fluffy+fur 。搜索结果格式化 /search.xml?q=fluffy+fur 。
13. 提供API的域名最好固定在一个子域名下。例如 api.xxxx.com 。也有按大的功能类别分为几个子域名，如FaceBook api.facebook.com graph.facebook.com 。对于直接访问子域名未做具体资源请求，则需做好页面重定向，提供更多信息给开发者。
14. 异常处理。对于客户端只支持有限的http方法，可将方法名添加至请求参数中，如 /dogs/1234?method=delete 。可以指定参数让服务端返回http状态码。
15. 授权。PayPal使用permissions Service API，FaceBook使用OAuth 2.0。推荐使用最新版本OAuth。
16. 提供优良的SDK文档。
17. 设计模式：外观模式