原文：Web APIs for non-programmers 文章作于2013年，部分链接已失效，这里先不做修改。

什么是API?

API 全称为 Application Programming Interface，即应用程序编程接口，理解 API 的重点在于理解什么是Interface 即接口。

接口随处可见，电脑的操作系统是一个接口，电梯上的按键是一个接口，汽车的油表盘也是接口。

接口运作在一个复杂系统的顶层（可以理解为是你最先接触到的应用层），它帮助我们简化特定的任务，它是一个出色的中介，将你从幕布后复杂的细节中解脱出来。Web API 就是这样工作的，比如Twitter 和Youtube 的接口，把你的行为转换为计算机系统可以理解的技术细节，帮助你简化工作。

什么是Web API?

Web API 有许多不同的种类，最常见的、非编程人员接触最多的叫做REST/ RESTful API。从现在起，我们讨论的Web API 默认为 REST API。

Web API 是通过URL 进行控制的接口。从这个角度来看，所有的Web 页面都是API。你通过浏览器发送一个URL request 即请求，Web 服务器通过请求进行一系列复杂的抉择，返回给你特定的内容即响应response。标准的Web API 有着相同的工作流程。

普通的URL 与作为Web API 一部分的URL 最主要的区别是：普通的URL 返回一些精心设计过的页面在你的浏览器中展示；而Web API URL 返回的结果却是未经美化的没有特殊样式的，用于计算机工作而并非像用户展示。

当你在浏览器中发送 http://twitter.com/ 请求，会返回一个有样式、图片、按键的页面，用户在浏览页面时喜闻乐见，然而如果你要从这个页面中获取并分析数据，一定会头疼不已。底层文件的结构是不连续的，你很难成块儿的获得数据；

而当你发送Web API URL 请求时，你得到的是一个未经修饰的成块儿的纯文本文件：

https://api.twitter.com/1.1/statuses/home_timeline.json

这个纯文本文件是给电脑读取的，没有样式化很难看，然而你如果要抓取和分析数据十分方便。

使用Web API 是一种屏蔽你不在意的无用的视觉界面，专注于获取数据的好方式。从某种角度上来说，你可以把Web API 看做进行Web 服务器数据库的短链接。Twitter不会让你登陆他们的数据库（除非你在那里工作），但是Twitter 通过API 给你提供了一种有限制的特定的方式访问数据。

为什么想要使用Web API?

1. 获取原本需要大量时间才能得到的信息。大多数时候，你可以直接从页面上得到信息，你可以翻阅点击100 个页面并且把页面中你需要的信息复制粘贴到你本地的笔记本或表格里。不过如果你是一个程序员，你可以花费时间在分析页面结构上，写一个个性化的抓取程序来获得数据。API 就是一个可以快速获得数据，节省时间的神器。

   例如：你想要获得Flickr 上所有tag 为’maui’ 、用Nikon 相机拍摄于2012年、宽大于高的照片，你可以人工在Flickr 上搜索，一次点开一个结果，检查是不是你需要的并将符合条件的照片复制下来。这可能会花费你很多时间。如果你使用API 的话，你可以更精准的获得你想要的信息，不用一个一个点击，你就会得到一个包含一切信息的文本列表。

2. 得到不使用API 无法得到的信息。有时API 提供一些你无法直接从页面上获取到的信息，这些信息不在页面上显示可能是因为大部分的用户不在意这些信息。

   例如：Twitter 可能只在页面上展示一个特定日期以前的推文，不过你仍然可以通过API 获取这一日期之前的所有推文。烂番茄也可能提供展示在页面以外的额外的元数据。

3. 使用实时数据使自动化App 运行。

   例如：你想要你的 “超级碗APP” 包括instagram 上实时的在场馆附近的照片。

4. 更加直接的使用接口为一个服务读写数据。

   例如：你使用“MailChimp” 管理邮件列表，你希望在指定事件发生时，能够自动添加和已出列表成员，而不依赖于手工的操作。

理由1 和2 都是非程序员可以用于简化数据获取的很好的方法，理由3 和4 需要你有更多的编程技术支持。

那么，API 是怎么工作的？

- 基础

首先，你需要知道你需要的数据是不是可以通过API 获得。最简单的方式就是查询网站的“API” 或“Developer”页面。有时也有些文档是非正式的，需要辨别？

通常你会找到API 文档，叫做 API 详细说明即 specification。这里有一些（可能已经失效）的例子：

The Twitter API: https://dev.twitter.com/docs/api/1.1

The New York Times Best Sellers API: http://developer.nytimes.com/docs/best_sellers_api/

这些文档看起来信息量巨大，不过主要给出了一些URL 列表，描述了通过这些URL 可以获得这样的数据。对于每个URL ，通常都会有一个页面或小节给出更多如何使用的细节，主要包括：参数parameters 和响应response。

- 参数

参数URL 的一部分，明确你需要的是什么样的内容。例如，你正在用Twitter 提供的API 做搜索，你使用的URL 可能是这样的：

https://api.twitter.com/1.1/search/tweets.json

你并没有告诉Twitter 你要搜索的内容是什么，你必须像这样给出参数来进行说明，你要搜索的是“burritos”：

https://api.twitter.com/1.1/search/tweets.json?q=burritos

参数也可以叫做变量即variables，因为它们是可变的，它们是URL 中可变的一部分，根据你想要查询条件的不同而变化。

对给定的URL 而言，有些参数是必须的，有些参数是可选的。还是以Twitter 搜索为例：

https://api.twitter.com/1.1/search/tweets.json?q=burritos

参数q 提供了一个搜索的关键词，这是一个必须的参数。如果你不提供，API 不会接受你的请求因为你并没有告诉它你在搜索什么。可选的参数相当多，比如，你可以添加一个lang 参数，来说明你需要返回的特定的语言。这样做，服务器会接受你的搜索请求，不过只会返回英文结果：

https://api.twitter.com/1.1/search/tweets.json?q=burritos&lang=en

这些只是冰山一角，URL 一般都有非常多的可选参数来更准确的定义你需要的内容。文档一般会列出这些参数的默认值，这很重要，比如默认一次显示的结果页面为15，如果你需要一次显示更多，你就需要修改这个参数：

https://api.twitter.com/1.1/search/tweets.json?q=burritos&lang=en&count=100

参数规定某些事项的细节，比如：

• 你一次希望得到多少结果？
• 你希望结果以怎样的方式分类？
• 你希望搜索的日期范围？
• 你希望搜索的位置？
• 你希望返回的结果是什么格式的？

你可能想知道这些参数怎样写在URL 里，我们一会儿在GET 和 POST里讨论（结果后面就没说了）。

- 响应

当你使用Web API 时，你提供URL （可能有一些额外的参数），你很可能得到响应，响应分为两种：

• 一些数据：这正是你需要的
• 关于你请求失败的解释 - 这可能会告诉你你缺少了某个参数，你可能超过了速率限制（后面会解释），特定的请求需要申请授权（后面会解释），或者这个请求有什么问题。

文档会给你每一类请求可能会得到的几种响应。后面有一些例子省略。

你得到的响应数据很有可能是两种格式的：XML、JSON。

- GET vs. POST

许多URL 需要参数，你可以通过以下几种方式提供：

• 修改 URL

  有时候URL 可能是这样展示的：http://www.api.com/list/[page number]/[sort by]/[format]/

  在这种情况下，你将方括号中的参数替换为你需要的结果就可以了：
  http://api.ebay.com/list/1/price/xml/ (Get page 1, sorted by price, in XML format)

• 在URL 的末尾添加GET 参数

  这和上一种方式差异不大，你把需要查询的条件通过 GET 参数列出来，每一个条件都有名字和值，像这样：
  ?name=value&name=value&name=value...

  在这个URL 里就是这样：
  http://www.google.com/search?query=ducktales&language=english

  你使用了两个参数：
  query：它的值是ducktales，language：它的值是english。

  大多数的Web API 都是通过这种方式来提交参数的，用于查询信息或获得列表。它们提供了基本的URL，你添加上附加的GET参数就可以了：

  http://api.yelp.com/v2/search?term=burritos&location=Chicagohttps://api.foursquare.com/v2/venues/search?query=burritos&near=Chicago

• 发送POST 变量

  如果文档写着你需要在请求中使用POST 方法，你可能会遇到一些问题。POST 用于在请求中发送隐藏的数据，数据并不在URL 的部分中列举。实际上你在浏览网页时经常使用到POST 方法：当你在网上购物，提交你付款信息的时候你就在使用POST 方法，如果没有POST，当你打开一个页面，你的信息直接显示在URL 上那该有多糟糕啊，像这样：
  http://www.amazon.com/checkout?creditcardnumber=1234567812345678

  POST 通常用于你不想也不需要在URL 中显示参数时，比如修改数据库中的数据。

  让我们想象一下没有POST，你把邮件地址添加到URL 的参数里：
  http://mailinglist.com/add?q=john@smith.com

  当别人得到并打开这个URL，他们会不停的 re-initiate that action，这个邮件信息会不停的添加进列表，不过如果你用POST 来代替一切就会好很多：

  http://mailinglist.com/add 你不需要重复动作一遍一遍的填表。

  如果你需要用到POST，你依然可以不写代码，不过有些复杂的是你不能直接在浏览器的地址栏上进行操作了，你需要借助一些软件比如 Fiddler，或者浏览器的扩展插件比如Postman or REST Client。这些工具都可以帮助你在请求中添加POST 参数。
  

- API keys

有些API 是完全开放的，这些API 你可以直接使用它的API URL，添加你需要的参数，在你的浏览器中提交请求，获得你需要的响应。

不过现如今大多数的API 都需要取得一定的授权，大多数的授权形式就是API Key，一个长字符串，包含字母和数字，起到密码的作用。所以在使用API 前你需要先申请Key，不过好消息是这个操作还算便捷，很多API 拿到Key 以后仍是免费的。

比如，如果你没有API Key，你通过烂番茄的API 搜索“skyfall”：

http://api.rottentomatoes.com/api/public/v1.0/movies.json?q=Skyfall

你会得到的响应是账户未激活：

{"error":"Account Inactive"}

当你申请到了API Key 并作为参数加入请求后，像这样：

http://api.rottentomatoes.com/api/public/v1.0/movies.json?q=Skyfall&apikey=krw98sa2

你就会得到你想要的结果了。

- 限制速率

许多API 包括限制，限制你一个小时或一天可以提交的请求数量，以避免你的行为给服务器造成过载。对于速率的限制信息，可以查看API 文档，你会发现有些API 对一定速率以内的使用是免费的，如果你希望有更高的速率，需要额外缴费。

非程序员API 使用流程

1. 你需要从某个服务中获取数据，这个服务提供API 吗？哇，提供免费的API；
2. 查看API 文档，找到你需要的URL；
3. 如果需要的话，注册API Key；
4. 列出合适的参数；
5. 将包含参数的URL 通过浏览器提交，如果不work，回到步骤4；
6. 拿到数据，解析数据。你需要了解XML 和JSON。