REST API 最佳入门指南

http://www.javashuo.com/article/p-myhxzlya-mg.html 

若是你看到这里，你之前可能据说过API 和REST,而后你就会想:“这些都是什么东西？”。也许你已经了解过一些这方面的知识，但殊不知道从何入手。在这个教程中，我将会诠释REST的基础以及如何给应用建立一个API（包括认证受权）。

什么是API?

API是Application Programming Interface（应用程序界面）的缩写，它是拿来描述一个类库的特征或是如何去运用它。你我的收藏的类库也许包含有可用功能的“API文档”，那些必需的参数咱们该怎么称呼它们？诸如此类等等。

然而，现在不少人参考API文档时，他们经常参考一种可能会经过网络分享你的应用数据HTTP API，例如，Twitter提供一个API能让用户在特定的格式下请求推文，以便用户方便导入到本身的应用程序中。这就是HTTP API的真正强大之处。它可以从多个应用程序中混搭数据到混合应用程序中，或是建立一个能加强使用他人应用体验的应用程序。

这样说吧，好比说咱们有一个能够容许咱们查看（view），建立（create），编辑（edit）以及删除（delete）部件的应用程序。咱们能够建立一个可让咱们执行这些功能的HTTP API:

当人们开始去实现他们本身的API接口时，问题就出现了。居然没有一个标准的方法来命名URL，人们老是要参考API才得知它是如何运做的。一个API中可能命名一个URL为/view_widgets，可是另外一个API可能就命名成/widgets/all.

不用担忧！REST帮你搞定这些混乱！

什么是REST呢?

REST是Representational State Transfer的缩写，它是由罗伊·菲尔丁（Roy Fielding）提出的，是用来描述建立HTTP API的标准方法的，他发现这四种经常使用的行为（查看（view），建立（create），编辑（edit）和删除（delete））均可以直接映射到HTTP 中已实现的GET,POST,PUT和DELETE方法。

HTTP 中的8中不一样的方法：

大多数状况下，当你在使用你的浏览器的点点看看的时候，其实只用到HTTP的GET方法。GET方法是在你向因特网请求资源的时候才会用到的。当你提交一个表单时，你就会常常用到POST方法来回传数据到网站上。至于其余的几种方法，某些浏览器可能根本就没有去彻底实现它们。可是，若是是供咱们使用的话，就没什么问题。问题是咱们有不少要选择去帮助描述这四大行为的HTTP方法，咱们将会用到那些已经知道如何去使用这些不一样的HTTP方法的客户端类库。

REST例子

让咱们来看下几个让API表述性状态转移化的例子，就用咱们以前说的那几个部件来解释：

解剖REST URL

你可能已经注意的前面的几个例子，REST URL使用着一套一致的命名方法。当你跟API交互时，你几乎常常操做一些对象。在咱们的例子中，咱们讲的是部件。在REST中，咱们称之为Resource。URL的第一部分常常是这个资源的复数形式：

/widgets

当咱们参考收集的资源时（list all：列出全部 和add one：新增一个），这将会常常用到。当你用到一些特殊的资源的时候，你就会给URL增长一个id，这个URL在你想要“view”，“edit”和“delete”特殊资源的时候会被使用。

嵌套资源

若是说，咱们的部件有不少用户使用，URL的结构又将会是怎样的呢？

嵌套资源在URL里是彻底兼容的，可是超过两层嵌套就不是很好的方法了。其实这根本不须要，由于你彻底能够以ID的形式参考到那些嵌套资源，总比嵌套在父类中好。例如：

HTTP 状态码

REST的另外一重要部分就是为既定好请求的类型来响应正确的状态码。若是你对HTTP状态码陌生，如下是一个简易总结。当你请求HTTP时，服务器会响应一个状态码来判断你的请求是否成功，而后客户端应如何继续。如下是四种不一样层次的状态码：

• 2xx = Success（成功）

• 3xx = Redirect（重定向）

• 4xx = User error（客户端错误）

• 5xx = Server error（服务器端错误）

如下是一些最重要的状态码：

请求成功的状态码：

• 200 – OK (默认的)

• 201 – Created（已建立）

• 202 – Accepted (已接受：经常使用语删除请求)

客户端错误状态码：

• 400 –请求出错（语法格式有误或服务器没法理解此请求）

• 401 – 未受权(须要登陆)

• 404 – 找不到 (找不到所请求的文件或脚本)

• 405 – 不容许此方法(错误的 HTTP方法)

• 409 – 冲突 (IE尝试以PUT请求建立相同的资源时)

API响应格式

当你请求HTTP时，你能够请求你想要接收的格式。例如，请求一个网页，你想以HTML的格式请求，或者若是你想要下载一张图片，返回格式应该是图片的格式。然而，响应请求格式是服务器的职责。

现在，JSON 已经快速发展成为REST API选择的格式，它有一个轻量级的、可读性又很高的语法，以至其很容易操做。因此，当使用咱们API的用户按他们想要的格式发出请求和指定JSON时。

要是用户请求一个咱们没有实现的方法的格式时，咱们又该怎么办呢？你大能够抛出一些错误的类型。但我建议你将JSON格式做为你的标准响应格式，由于这是开发者想要的格式。没理由去支持其余的格式，除非你已经有一个可支持的API。

建立一个REST API

事实上，建立一个REST API是超出此教程范围的，由于它是有特定语言的。但我将以Ruby（一种为简单快捷的面向对象编程而创的脚本语言）的方式给出一个简易例子，它使用一个叫Sinatra的类库（不懂得能够自行百度）。

API受权认证

在通常的网页应用中，认证操做是常常要接收用户名和密码的，而后在session中保存用户ID。用户的浏览器就会保存会话中的ID到cookie中。当用户在网站上访问须要认证受权的页面时，浏览器就会发送cookie，应用程序就会查找seesion会话中的ID（若是它没有失效的话），因为用户的ID保存在seesion中，用户就能够浏览页面了。

用这个API，就可使用seesion会话保存用户记录,但这毕竟不是最好的方法。有时候，用户想直接访问API，或是用户想本身受权其余应用程序去访问这个API。

解决方法是在认证的基础上使用秘钥。用户输入用户名和密码以登陆，应用程序就以一个特殊秘钥返回给用户以备后续之需。这个秘钥能够通入应用程序，以致于若是用户想要选择拒绝应用更进一步的接入时，能够撤回这个秘钥。

其实，网上已经有一个作上面这件事的很流行的标准方式，叫作OAuth（开放受权：是一个开放标准，容许用户让第三方应用访问该用户在某一网站上存储的私密的资源（如照片，视频，联系人列表），与以往的受权方式不一样之处是OAUTH的受权不会使第三方触及到用户的账号信息（如用户名与密码），即第三方无需使用用户的用户名与密码就能够申请得到该用户资源的受权，所以OAUTH是安全的。），特别的，标准第二版的OAuth。网上有不少很是好的实现OAuth的资源，因此我才说那是超出此教程范围的。若是你正在使用Ruby，这里有一些帮你解决大多数工做的很好的类库，好比OmniAuth 。

花了那么多时间给大家讲解这个教程，但愿对大家有所帮助。