什么是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文档是一个正在发展的领域。建议你亲自尝试，看本身是否感兴趣。咱们须要更多优秀的文档工程师。

做者：泡芙小超人