什么是API文档？--斯科特·马文

有时候，软件开发人员想要的是自己的软件被其他应用软件所应用，而不是让人来操作。API使各种应用软件互相通信成为了可能。

从事API文档写作15年，我亲眼见证了API产品的崛起。各个公司开始搭建平台，希望别人接入平台并使用平台提供的API。API的发展意味着API文档的增多，这对技术文档工程师无疑是一件好事。 

在本文中，我会阐述什么是API，API文档应当包含什么，该类型的AP文档面向哪些读者，以及如何在这个领域快速入门。



什么是API？

有时候，软件开发人员想要让自己的软件被其他应用软件所应用，而不是让具体的人来使用。因此互动就是和其他软件之间的，而不是一个人，所以就需要达成一个约定的方式去互动。这种语言，和其内在的一系列规则就被称作应用程序编程接口（API）。基本上，API使各种应用软件互相通信成为了可能。

你的软件与API之间的信息交换经常表现为一个请求和一个回应的形式。你的软件用API发出一个请求，另一个程序则通过API返回响应。

有的API被用来在产品和外来产品之间交换数据。如果你想与Google 或Twitter交互，你可以参考他们的API来写代码，从而在你的产品和他们的产品之间进行数据交换。 

有的API被用来在一个公司内部或者一个产品之间进行内在数据交换。Windows和Android操作系统都有内嵌API，以便开发人员编写出可以让系统中不同模块互相通信的子程序。

还有的API被用与内部以及外部的交流。亚马逊网站服务中有40多个服务都有给任何人使用的API。亚马逊开发人员也会自己使用这些API，使各种服务之间可以互相通信。

不管是被内部还是外部使用，API都需要形成文档，以确保产生通信。



什么是API文档？

API根据语言和功能的不同而有多样化地形式，但是它们都有一个共性：用户发出一个请求，API（有时候）返回一个响应。技术文档工程师的任务就是详细描述请求包含什么，请求的形式是什么，以及返回的数据是什么。

API文档的结构虽然多种多样，但是我认为一份好的API文档需要给读者展示：

•操作的语法
•操作具体可以干什么
•操作涉及哪些变量，包括系统设定值，有效值，以及数据类型--布尔值、字符串，等等
•操作的返回值是什么
•操作可能会遇到的报错信息
•请求和响应的举例 

这些听起来很多，但是所有优秀的代码都包含这些内容。API文档工程师需要做的就是去查看，询问，以及像一个编辑一样去识别和减少代码里没有的内容。

就核心而言，API文档细化了代码里面的内容：可用的命令，命令的作用，以及各个命令的变量。传统来说，API文档描述了一个操作以及如何发出一个请求。一般是由包含参数名称及参数取值的表格和代码样例组成。一个功能一个API文档，将所有文档组合，就是一份API参考指南。很基础，但很有用。

但是针对那些不单是发出一个简单请求的API文档应当怎么写？大多数开发人员想知道API是如何把各个命令串到一起，以及如何在输入和输出间互动。针对这一点，很多文档工程师编写了开发指南，包含API的常见使用场景案例和任务，以及代码样例。

另一种形式的API文档，叫做“用户指南”，内容跟代码不相关，倾向于解释API的相关命令行界面或图形用户界面。“用户指南”通常包含了用来辅助理解API的概念、安装部署、配置任务、以及最佳范例。

如果文档工程师想要降低API的使用难度——从根本上帮助任何一个有电脑的人使用API—他/她将会开发一个“快速入门指南”。这类文档通过执行一系列任务引导用户理解API，加深对API操作和后续任务的了解。

一些公司会把上述各类API相关文档打包，以软件开发工具包（SDK）的形式发布。使用SDK的人们通常希望里面包含的不只是API文档。通畅情况下SDK应当包括代码，测试平台和文档。

基本上，API文档的读者都关注这两个方面：正确的信息和可执行的代码样例。



谁会使用API文档？

在技术沟通交流中，我们经常会把读者分为三大类：终端用户、系统管理员、开发人员。我开始相信，无论是哪种文档，每个读者都只是一个某种意义的终端用户。一些终端用户想要知道如何在应用中创建新文件。一些终端用户想要知道如何在一个终端或命令提示运行一个命令。还有一些终端用户想要知道如何开发和其他程序交换数据的程序。

API文档的终端用户通常是开发人员，但是也有一些针对系统管理员的API文档。系统管理员通常查看API文档是为了运行不需要编程的但必须在基础应用上运行的任务。传统来说，这是和命令行操作一起的。比如，为了在一个账户中创建一个用户，系统管理员会执行一个命令来生成一个密匙，这样用户就可以开始对API发出请求。 

另一方面，开发人员，或许想创建一系列可以在特定时间、特定场景下下以编程方式运行的操作。例如，当一个请求被返回，第二条命令会用第一条命令的返回值运行。在这种情况下，开发人员就要创建一个使用API功能的工作流或框架。 

一些API是针对特殊命令，比如，“这一刻及时备份我的数据库”。一些是以重复性和编程性的方式被使用，比如，“当我的网页服务器达到80%忙碌时，创建另一个网页服务器，在两个服务器中分担负载”。



谁来编写API文档？

在这个日益发展的行业中写作API文档的人通常被称作“程序文档工程师”或者“高级技术文档工程师”。通常有两条路可以成为一名编写API文档的工程师。第一条路是指那些有很长时间写作经验，擅长沟通实践，并且决定开始写作API文档的人。这一条路叫做“边写作边学习代码”。

第二条路是指那些决定致力于写作的开发人员。这条路叫做“边写代码边学习写作”。是一条边开发边学写作的路。

本文针对走第一条路的探路者。如果你对API文档写作感兴趣，遵循下面这几条方法，你将受益匪浅：

•学习读懂代码。意思是读懂代码，不是必须会写。通过各种途径查看阅读代码里的注释，尝试理解代码的含义。写作API文档需要对一种编程语言有基本了解，不一定要成为一个开发人员。当然，你应当要知道看如何看代码。大体上，你需要理解这个代码是干什么、它为什么被开发、预期目的是什么、以及谁会在什么情况下使用它。

•学习API技术常识。正常来说，API信息内容要么用可扩展标示语言（XML），要么用对象表示法（JSON），每一个文件格式都比较容易理解。但是在仍然建议通过入门书去了解了解。当API通过表述性状态转移（REST），或是采用简单对象访问协议（SOAP）开发，你可以通过一本好书或者Google搜索就可以学到这些。

•查阅不同的API文档。查看已有的总是好事，例如亚马逊弹性计算云文档：(https://aws.amazon.com/documentation/ec2/)，谷歌云存储XML API：(https://developers.google.com/storage/docs/xml-api-overview)，还有Twitter的API文档：(https://dev.twitter.com/docs/api)。

• 保持谦逊。向专家讨教代码疑问，最好的开发人员有时都会去向别人咨询一些代码上的疑问。如果他们都会如此，文档工程师也不可能全都清楚。但是要记住了：一定要事先准备一下，不要因为自己没有先调查清楚，浪费开发人员的时间。

•增长你的好奇心。如果API有工具包或者测试桩，试着用代码玩一玩。使用API发出一个请求，看会发生什么。

听起来有好多工作要做，好多东西要学习，但是你只要开始，会发现也就小菜一碟。API文档是一个正在发展的领域。建议你亲自尝试，看自己是否感兴趣。我们需要更多优秀的文档工程师。