【翻译】Win with APIs by keeping it simple

#Win with APIs by keeping it simple

原文：Win with APIs by keeping it simple

译文Github地址:Win with APIs by keeping it simple

少便是多

##简单易懂

就像你不须要阅读使用手册就知道如何使用 iPhone 同样，一个好的 API 也不须要你先花上数天时间来摸清如何使用 API，而后才能展开工做。

做为开发者，不论你对 Facebook 自己或褒或贬，有一点不能否认，它的 API 设计很是直观和简单：一旦你经过了认证，接下里的事情就水到渠成了。

在浏览器里面输入 https://graph.facebook.com/534822875 ，就能够获得 ID 为 534822875 的用户信息，JSON 片断以下【译者注：这个可能与实际结果有出入，一切以原文为准】：

{
   "id": "534822875",
   "location": {
       "id": "114952118516947",
       "name": "San Francisco, California"
   }
}

Facebook 还建立了一个简写形式：using /me 来表示当前已经登录的用户，也就是说，https://graph.facebook.com/me 能够获得和上面同样的结果。【译者注：这个须要登录以后才能有结果，因此，实验结果根据登录状态和用户 ID 的不一样而不一样】

事实上，我经过本身在使用 Facebook 的功能（friends, photos, likes）时了解到的信息，几乎就能够猜到各个功能对应 API 的功能和方法名称了。

好比，https://graph.facebook.com/me/likes 返回我在 Facebook 上的喜爱列表：

{
   "data": [
       {
           "category": "Media/news/publishing",
           "name": "The Guardian",
           "created_time": "2014-08-01T01:32:17+0000",
           "id": "10513336322"
       },
       {
           "category": "Movie",
           "name": "The Lives of Others Movie",
           "created_time": "2014-07-31T15:47:14+0000",
           "id": "586512998126448"
       }
   ],...
}

这个 API 很是直观，基本上就能猜到里面的有效资源字段名称。

那如何得到个人照片列表呢？

没错，就是：https://graph.facebook.com/me/photos

一样是获取照片列表，Flickr 的 API 是这样的：

https://api.flickr.com/services/rest/?method=flickr.people.getPhotos

人们能够有无数对 Flickr API 的吐槽：好比“不是 RESTful 风格”等等。可是，最重要的问题仍是：不够简单。 既不直观，也不容易记忆，更不容易理解。做为一个使用者，我老是须要回过头去对照 API 文档来使用，这一点阻碍了他的使用体验。

对照来看，Facebook 的 API 就简单直观得多，能够快速上手并当即开工。这也是为何会有超过 2 万的开发者使用 Facebook 的 API 建立了超过 1百万 app 的缘由。

##简单易用

使用 RESTful 的方式来构建API，能够帮助你遵循“理解简单”的原则，也意味着你能够像浏览器同样来处理 http 资源。 这会帮助你将 API 构建在实际的项目和业务关系上，当你在谈论 API 的时候，能够紧密的关联到员工，客户和用户所谈论的业务上，这将是一个巨大的好处。

下面的 RESTful 风格 API，经过它能够获取帐户列表或者某个特定的帐户信息：

# 列出全部帐户
GET /accounts

# 显示帐户信息
GET /accounts/{account-number}

下面的 API 构建在一个真实的生活场景之上，其返回一个特定帐户的信息：

GET /accounts/6242525/balance

你能够想象这样的场景，某个客户打电话过来问：个人帐户号码是6242525，你能帮我查一下个人帐户余额吗？

经过这种方式，就至关于用一种通用而富有表现力的语言在你的 API 和业务之间创建了一种映射，使得用户更容易理解。 使用 RESTful 的另外一个好处是，能够方便的在浏览器中使用，实验验证也相对简单。

#数据格式简单

这么些年，开发者们已经厌倦了冗长的XML等格式。他们再也不愿意编写自定义的解析器，转而寻求更轻量级的选择。JSON解决了这些问题，而且 JSON 正成为一个事实上的数据交换格式。 另外，像许多 API 用户同样，若是你在使用JavaScript，那么就可以很容易的集成JSON。

JSON是简单的键值对表。看看前面的例子，你能够看到，我喜欢“Guardian newspaper”，点赞时间是“2014年8月1日”

{
   "category": "Media/news/publishing",
   "name": "The Guardian",
   "created_time": "2014-08-01T01:32:17+0000",
   "id": "10513336322"
}

##API 导航

经过提供分页连接，导航 API 就很容易实现了，API能够直接告诉用户下一步的目标在哪，而无需用户去手动构建通往下一步的 URL，这一点在处理大型数据集方面显得特别重要。 如下是来自 Facebook’s Open Graph API 的优秀例子：其中全部响应都含有一个“paging”属性，它告诉用户在哪里能够获得上一个或下一个数据集。另外一个好处就是，机器人或爬虫能够经过一样的方式来浏览你的API。

{
   "paging": {
       "previous": "https://graph.facebook.com/me/albums?limit=5&before=NITQw",
       "next": "https://graph.facebook.com/me/albums?limit=5&after=MAwDE"
   }
}

##扩展用法

让用户可以控制 API 的行为是一个强大的特性。有不少方法能够作到这一点，包括使用各类排序规则，搜索和过滤。 “字段过滤”就能够用来指定响应中应该包含哪些字段。这种特性在带宽或性能受限，或者其中用户只关心响应中的部分字段的状况下特别有用。 过滤的另外一个好处是，将选择交给用户，让用户告诉 API 什么是他们关心的，从而使得 API 的建立者没必要针对每一种需求来开发不一样的 API。

https://graph.facebook.com/me/likes?fields=category,name

上面的 API 调用告诉 API 在响应中只须要返回 “category” 和 “name” 字段便可。

{
   "category": "Media/news/publishing",
   "name": "The Guardian",
}

##维护简单

全部的API须要支持向后兼容，同时它也应该给用户提供一种只使用某个特定的版本的方法。要作到这一点，最简单的方法是在基础 URI 中包含版本号，而后默认不包含版本号的 URI 做为最新的API版本。这样作就给 API 用户一个使用特定版本或者最新版本 API 的选择余地。

versioning （选择版本）

/api/v1.0/accounts/12345 /api/v1.1/accounts/12345 /api/v2.0/accounts/12345

alias no-version to the latest version（最新版本）

/api/accounts/12345

API 的建立者须要当心的维护 API 使用规则，任何更改都须要通过认真的检查审核，并与用户沟通以防止惹怒用户。

##SSL

安全是一个关键因素。使用 HTTPS，经过加密和验证，以保证用户和服务器之间的通讯的完整性，并防止中间人攻击， 从而提供一个安全的 API 访问环境。 甚至能够考虑不提供经过非安全HTTP 的 API访问。

##操做简单

当你的 API 有数百到数千用户的时候，你须要考虑一整套的高级特性支持。

##访问控制

您须要为开发人员提供 key 访问您的API，阻挡黑客入侵。你也会但愿限制API用户的流量，防止用户的行为致使API崩溃——不论他是有意或无心的。

##监控

你须要知道你的 API 什么时候失效，什么时候必须重启。你还须要知道你的 API 使用状况：是谁在什么时候何地使用 API？。

##集成

您可能须要向用户提供 API 使用状况的分析和报告，也可能须要集成一个计费系统，为 API 使用收费。

其中一些特性是不容易实现的。事实上，实现这些特性多是整个 API 开发周期的更复杂的方面之一。可是万变不离其宗，再次强调，核心仍是要保持它的简单。 不要试图推到重建本身的方案，相反，使用现成的 API 方案来管理您的API。将精力投入到业务相关的部分，从而与你的竞争对手产生差别化。

建立一套成功的API，使得架构和业务更加灵活，甚至将推进业务和收入增加，并激励创新。 要记得——保持简单！