创建 REST API 的最佳入门教程

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

什么是API?

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

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

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

http://example.com/view_widgets

http://example.com/create_new_widget?name=Widgetizer

http://example.com/update_widget?id=123&name=Foo

http://example.com/delete_widget?id=123

当人们开始去实现他们自己的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中不同的方法：

GET

POST

PUT

DELETE

OPTIONS

HEAD

TRACE

CONNECT

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

REST例子

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

如果我们想要查看所有部件，URL将是这个样子：

GET http://example.com/widgets

用POST方法新建一个用来发出请求数据的部件：

POST http://example.com/widgets

Data:

name =Foobar

用GET方法查看一个简单的部件，我们从指定的部件id中获取：

GET http://example.com/widgets/123

用PUT方法发送新数据来更新部件：

PUT http://example.com/widgets/123

Data:

name =New name

color = blue

用DELETE方法来删除部件：

DELETE http://example.com/widgets/123

解剖REST URL

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

/widgets