Web Api 端点设计 与 Oauth

最近一直看这方面的东西，总结以下：

在后续会进行实例demo演示，本篇进行理论详解。

下篇相关博客：

《Web Api 内部数据思考 和 利用http缓存优化 Api》

《API接口安全增强设计方法》

一 什么是Web Api ?

     web api 是指 “使用HTTP协议经过网络调用的API”。API是“Application Programming Interface”的缩写，是软件组件的外部接口。也就是说某个软件集合体，人们能了解它的外部功能，但并不知道（也无需知道）其内部的运做细节，为了从外部调用该功能，须要指定该软件集合体的调用规范等信息，而这样的规范就是API。—— web api的设计与开发一书解释

二 什么是API端点 ？

　 端点是指用于访问API的URI，由不一样的功能而拥有不一样的端点。以获取用户信息为例，能够分配以下URI

https：//api.example.com/v1/users/me

三 URL和URI有什么区别？

     URI，是uniform resource identifier，统一资源标识符，用来惟一的标识一个资源。而URL是uniform resource locator，统一资源定位器，它是一种具体的URI，即URL能够用来标识一个资源，并且还指明了如何locate这个资源。也就是说，URI是以一种抽象的，高层次概念定义统一资源标识，而URL则是具体的资源标识的方式。URL是一种URI。

四 端点的基本设计

1 容易记忆，URI包含的功能一目了然

  A） 短小便于输入的URI

　　  简单易记，例如：

http：//api.example.com/service/api/search

        这个URI很差的地方在于：

　　1）域名和路径都包含api，重复 。

　　2）service 表示服务，彷佛可有可无

　　能够简写为：

http://api.example.com/search

　　固然，能够添加其余区别的路径名

B）能够读懂的URI

　　例如：

http：//api.example.com/sv/u

　　sv和u是啥？service和user吗？

C）没有大小写混用的URI

　  在web设计标准一书中，说的是尽可能路径采用小写

http://api.example.com/USERS/12345

与下面对比

http://api.example.com/users/12345

　　这方面见仁见智

D）修改方便的URI

　　假设咱们须要获取某种商品（item），例：

http://api.example.com/v1/items/123456　　

　　能够看到v1为版本号，items为商品，而且能够知道改变id，能够获取到其余商品

E）不会暴露服务器架构的URI

例如：

http://api.example.com/cgi-bin/get_user.php?user=100

这透露api是由php语言编写且以CGI的方式运行。这是多余的，对于外界来讲，并不须要关心语言和运行方式。也增长了服务器受攻击的可能性

F）规则统一的URI

Tips:查询参数放于路径中：例：

http：//api.example.com/v1/user/123:(id,name,desc,other)

五 登陆与OAuth2.0

　　官方网站：http://oauth.net/   http://oauth.net/2/

　　权威定义：OAuth is An open protocol to allow secure authorization in a simple and standard method from web, mobile and desktop applications. 

　　OAuth是一个开放协议，容许用户让第三方应用以安全且标准的方式获取该用户在某一网站、移动或桌面应用上存储的私密的资源（如用户我的信息、照片、视频、联系人列表），而无需将用户名和密码提供给第三方应用。

（换句话说，假设带有用户注册功能的在线服务A，对外公开了api，你本身开发了在线服务B，即可以使用在线服务A的用户，A用户也无需注册，便可使用服务B）

　　OAuth 2.0是OAuth协议的下一版本，但不向后兼容OAuth 1.0。 OAuth 2.0关注客户端开发者的简易性，同时为Web应用，桌面应用和手机，和起居室设备提供专门的认证流程。

OAuth容许用户提供一个令牌，而不是用户名和密码来访问他们存放在特定服务提供者的数据。每个令牌受权一个特定的网站（例如，视频编辑网站)在特定的时段（例如，接下来的2小时内）内访问特定的资源（例如仅仅是某一相册中的视频）。这样，OAuth容许用户受权第三方网站访问他们存储在另外的服务提供者上的信息，而不须要分享他们的访问许可或他们数据的全部内容。

　　新浪微博API目前也使用OAuth 2.0。

　　在OAuth2.0的处理流程，主要分为如下四个步骤：

　　　　1）获得受权码code

　　　　2）获取access token

　　　　3）经过access token，获取OpenID

　　　　4）经过access token及OpenID调用API，获取用户受权信息

　　上面是流程的大概四个步骤，流程图为：

【图片摘于网络】

　　第一步：首先直接跳转至用户受权地址，即图示 Request User Url ，提示用户进行登陆，并给予相关资源受权，获得惟一的Auth code，这里注意的是code只有10分钟的有效期；

　　第二步：获得受权code后，这一步就是请求access token，经过 图示 Request access url ，生成获得数据Token；

　　第三步：经过Access Token请求OpenID，OpenID是用户在此平台的惟一标识，经过图示 Request info url 请求，而后获得OpenID；

　　第四步：经过第二步获得的数据Token、第三步获得的OpenID及相关API，进行请求，获取用户受权资源信息。

六  数据格式

　　无疑，json是最流行的数据格式，其次是xml，同时还有jsonp【不推荐使用，最大的问题在于当服务器返回错误时没法正确应对】，那么如何指定返回数据格式呢？

　　1）使用查询参数的方法，例：

http://api.example.com/v1/user?format = xml

　　2）使用扩展名的方法，例：

http：//api.example.com/v1/users.json

　　可是此方法并不推荐，灵活性很低

　　3）使用名为Accept的请求首部来指明所需的数据格式，例如：

GET /v1/users Host : api.example.com Accept : application/json

　　既然第二种不推荐，那么能够第一种和第三种结合的方式设计api。

　　未完待续。。。。。。