《Web-API 的设计与开发》感想清理

在 Weibo 上无意间看到一个 Sina 的大牛发微提到了这本《Web-API 的设计与开发》，表示这本书不错，一个下午也就可以读完。虽然这两年来都是写后端，Web API 几乎是离不开的工作内容，但总觉得在这方面的知识视野不行，刚好也正想看看 Web API 相关的科普知识，于是就在 amazon 上弄了一本。
早上下的单，下午下班时就拿到了书，坐在回去的公车不惊的看了起来… 对于自己来说书中没什么晦涩的专业名词，几乎没有多少新的概念很快就可以浏览完一页，看起来也很顺畅，上有些算是在复习工作中所用的技术点，有些则是让自己在 web API 真的开阔了一点视野。

HTML4.0 只有 GET,POST 这两方法，也够用了，直到现在也看到有很多只用这两种方法去进行 HTTP 操作的，也理会简单一些；像 PATCH,PUT,DELETE 等新的方法是 HTML4.0 之后出现，其中 PATCH 方法在修订的时候定下来了，后来没人使用就删掉了，现在又加回去了！所以只要技术满足，该怎么方便还是怎么用；比如在实际工程中要统计点击或者曝光请求时，使用 GET 方法即方便拼接请求参数又可以减少数据传输（没有 BODY), 特别是在 URL 的长度限制已经增大了不少的情况下。HTML 不同 level 的特征：前一个：只有 GET,POST，现在 RESFUL API, 下一个 level: 当前 API 返回的内容里面携带了下一步要访问的 API, 比如当请求 list API 时下一步通常会对 item of list 进行操作，list API 返回时就会带有对 xxxItem 操作的 URI 信息
所谓的 RESFUL API 就是尽量用 GET,POST,PUT,DELETE,PATCH 方法作为操作运作，URI 中尽量不要使用出 CREATE,UPDATE 等动词；当然像一些大厂也会出现带 SEARCH 这类动词的 URI 的 API;RESFULT API 有时候还是有点繁琐的，但是它的出现肯定有它的原因，这就只是一种规范，实际工程中该怎么方便和高效就怎么来。
200,404,503 这些频繁出现状态码不在话下，像 2 系、3 系、4 系和 5 系 HTTP Code 的常见的如 201,301,302 对应的加强版 307,308,403 这些在 RESTful API 中也是很常见的，日常开发中没怎么遵循 RESTful API 原则（怎么方便怎么搞），没怎么留意，但想想这些 HTTP Code 还是很有用，比如说像请求的 URI 如果不对直接返回 404 而不再去读取 http body，这样 server 就可以减少一点工作；访问频率控制时遇到异常直接把返回在相关 HTTP Code 可以防止一些恶做剧的请求等等，特别是对于要服务大量请求的 API server 来说这些小小的规范很可能带不小的收益。
原来 HTTP 的 header 中把 reference 写错了（错成 referrence?), 搞得好一波人也跟着错；这类标准类文档影响真不小的。
使用 JSONP 进行跨域请求只能用 GET 方法
概括了 API 的版本表现：放在 URI 中，也是目前看来最常用的.e.g /v1/xxapi; 作为参数 xxxx?version=yyy; 使用日期作为版本号等；
no-store 与 no-cache 还是有区别的，一般以为不保留缓存就应该在 Cache-Control 这个 header 指定 no-cache，其实 no-store 可以实现得更直接一点；与缓存相关的 ETag,expires,varify 等 header 都应该有所认知；在 HTTPS 已经大规模使用的环境下，与安全相关的 security headers:X-XSS-Protection,X-Frame-Options,X-Content-Type-Options,Strict-Transport-Security 等都应该有所了解和认知。
还有不少很实用的 tips: API Blueprint; API Console 工具如 Graph API Explorer,Apigee 等