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。

　　未完待续。。。。。。