【第555期】API Blueprint 指导手册

apiblueprint，你有了解过吗？...



前言

这篇不会很技术，只是有次周会提到前端定义接口的问题，那么定义接口的文档会采用哪些方式呢？是word还是pdf？另外apiary这个词也是在某微信讨论组看到的，昨天就稍微延展了解下。

正文从这开始～

API Blueprint是一套API描述标准，和Markdown一样，属于一种标记语言，可以把标记文稿转换成漂亮的接口文档。

在这里我们假设开发一个关于Gist的接口文档：Gist Fox API，以此来学习API Blueprint的全部核心特性。

Gist是一个粘贴工具，用户把内容粘贴后会得到一个URL，通过这个URL可以访问先前粘帖的文本，方便地共享文本或者代码。具体可以参考Github提供的GitHub Gists服务。

我们将在我们的API中提供如下功能：

• 列出所有的Gist
• 搜索一个Gist
• 创建一个Gist
• 编辑已有的Gist
• 给一个Gist星标
• 给一个Gist取消星标
• 检查一个Gist是否星标
• 删除一个Gist

Gist Fox API

刚开始的时候，我们的Gist Fox API是这样的：



我们刚刚做了什么？接下来让我们一行一行的来分析一下。

元数据Metadata



你需要使用一个元数据(metadata)，来明确指定API Blueprint的版本。
比如在上述文件中我们使用的版本号是1A。

接口名称API Name



每一个好的API都应该有一个名字，我们的API也是这样：Gist Fox API，使用Markdown中的#标记表示API的名字。

接口描述API Description



在API的名字后面可以用Markdown的语法加上一些API的解释。

Markdown

如果要写一个blueprint文档，你唯一需要的就是一个文本编辑器，最好是一个Markdown的文本编辑器，VI和Byword都是不错的选择，在线的文本编辑器也没有任何问题。你甚至可以直接在Github的仓库里编辑bluePrint格式的文档。

如果你完全不知道Markdown，现在是一个学习的好机会。只需要点击Markdown Tutorial就可以开始学习。学完了可别忘了回来看看，我们这里也很精彩！

如果你需要查阅Markdown的语法可以直接点击Gruber’s Original查看。

First Resource

我们第一个要写的内容是根目录(root)，我们API的入口可以这样定义：



这些奇奇怪怪的内容是什么呢？让我们挨个来看一看。

资源Resource



在Blueprint里，所有的数据信息都是资源(resource)，比如用户、视频、文章。

resource的定义以#开始，中间是resource的名称，最后是用中括号包围的路径(URI)，需要注意的是URI是放在[ ]中的。URI是相对路径，在这里它就是个/。

资源描述Resource Description



我们可以用Markdown的语法在resource名称的后面加上包含API名称的说明。

在这里Gist Fox API是API名称，entry point是说明。

行为Action



行为action是一个HTTP请求的属性之一，在发送请求的时候会随数据一起发送到服务器。

我们在这里定义了一个action叫做Retrieve Entry Point (索引入口)，它是一个GET类型的请求。我们可以在后面加上一些描述，但是因为这个action的名字(Retrieve Entry Point)已经把这个行为解释的很清楚了，所以我们就跳过了这一步。

一般来说常见的action，包括GET和POST两种。在Blueprint有以下四种action：

• GET ： 获取数据
• POST ： 添加数据
• PUT ： 更新数据
• DELETE ： 删除数据

回应Response



在API Blueprint中一个action应该至少包括一个回应(response)。response是指当服务器收到一个请求(request)时候的响应。

在response中应该有一个状态码status code和数据payload。

在这里我们定义最常见的状态码：200，表示请求成功。

响应负载Response Payload



一个响应(response)经常包含一些负载(payload)。一个负载(payload)通常包含负载体(body)和负载头(header)两个部分。

在这个例子中，我们采用application/hal+json类型作为返回数据的类型。

Complex Resource

有了前面的根路径作为入口点，我们可以继续后面的内容。既然我们的API是围绕Gist展开的，那就让我们来给Gist一个明确的定义，以及一个用来获取它的action：



我们定义了一个和Gist相关的组Group，我们也定义了一个Gist resource以及它的模型阐述，还有一个能够获取Gist的action。

让我们来把它拆散了看一下。

资源分组Groups of Resources



我们的API最终会提供很多的资源，所以我们需要将相关的内容归类并分组。现在我们先简单的把所有的资源都归类在一个Gist组中。

不同的分组可以通过在开头的关键字Group区别。

URI模板URI Template



在URI中的变量需要遵守URI的模板格式，在这个例子中，Gist的编号(id)在URI中就是{id}。

URI参数URI Parameters



这个id变量是这个resource中的一个参数(parameter)，我们定义它的类型为string，并且在后面加上一些解释。

资源模型Resource Model



资源模型Resource Model是前面定义的资源的一个样例，它可以在任何一个request或者response需要的位置引用，一个资源模型有着和前面所说的payload一模一样的结构。

在前面的例子中，还包含了一个额外的描述，也就是在+ Model和+ Headers中间的那部分内容。

引用资源模型Referring the Resource Model



有了资源模型(Gist Resource Model)，定义一个获取Gist的action就很容易了，直接写上[Gist][]就可以返回一个Gist资源。

Modifying a Resource

接下来我们来写一个修改Gist的行为(action)：Edit a Gist，和删除Gist的行为(action)：Delete a Gist。



我们来看一看这个payload中的新内容：

请求中的负载Request and its Payload



我们需要接受一些输入来修改资源(Gist resource)，这些输入是访问请求(HTTP Request)的一部分，在上面的例子中定义了这样的一个请求以及负载payload的内容。

空负载Empty Payload



在Delete a Gist这样一个删除的操作中，我们的返回内容只包含一个204的状态码而没有其他内容，这个204的状态码表示服务器成功执行了这个请求。

Collection Resource

既然已经有了单个资源的接口，接下来我们来定义一个集合(Gists Collection)接口：





在这里你应该基本都熟悉这些接口了，除了其中的一个查询的参数：since。

查询参数Query Parameters



作为URI的参数，查询参数的定义必须符合URI模板格式，而这里有所不同的是，查询参数里有一个问号，并且它总在URI的结尾处。

Action-specific Query Parameters



通常查询的参数是针对诸多行为(action)中的某一个，所以我们只需要考虑和这个action相关的内容.

Subsequent Resource

最后一个缺失的部分就是星标资源的功能了，利用前面所学的知识，我们可以这样定义：

Complete Blueprint

你可以在API Blueprint的示例源码库，找到完整的Gist Fox API。

API Blueprint Tools

随着Gist Fox Blueprint接口文档的完工，接下来就应该让它发挥作用了。可以在Github中查看渲染结果或者在Apiary中查看渲染结果。可以前往apiblueprint.org的Tooling Section寻找更多的相关工具包。

后语

• 看到最后呢，在淘宝应该有一个不错的可视化的web接口管理工具，那就是RAP，地址是http://rapapi.net。有兴趣的可以了解看看，可在线用淘宝的，也可以下载下来自己部署。
• 另外想了解下，大家在这块接口上的处理方式是怎么做的，有兴趣的可以分享看看。
• Api blueprint提供了不少的工具，包括编辑器插件，模拟数据等。具体链接可以查看原文。记得看完有兴趣的可以实践一下

关于本文

作者：@callmewhy

原文链接：http://blog.callmewhy.com/2014/06/05/blueprint-tutorial/

    关注 前端早读课