API 设计: 想清楚了再写代码（1）

作为软件开发人员，我们很难抗拒把自己的想法写成代码的冲动。当突然有了想法，我们的手指就无法控制，就行一群野兽一样在键盘上疯跑，想用最快的速度实现我们的想法。

尽管这种感觉特别爽，但是我们最好还是退一步思考下，特别是当你创建的东西会被很多人使用，比如一些公共API。在此篇文章中，我讲为大家说明为什么和如何去设计一个深思熟虑的API。

API（Application Program Interface）是一个用于定义应用程序接口的通用术语，换句话说，就是人或者机器是如何与机器进行交流的。在web开发领域，一个API就是一个站点回复客户端请求的结构化文本数据的途径。

另一个被web开发者广泛应用的理念是 RESTFul Web API. 是由 Roy Fielding 定义，其作为一种架构风格，它提供了一个完善的客户端和服务器之间的通信协议。它有一些限制： 无状态通信，基于已有的技术（一般是HTTP），使用超媒体作为引擎状态。
换句话说，它提出了一些构建web API 的模式。为了简单起见，本文引用的Web API都是简单API。

一个JSON胜万言（One JSON is worth a thousand words）

看一个API响应的例子：

{
  "data": [
    {
      "story": "Jonatas Baldin was writing a blog post.",
       "created_time": "2017-15-01T00:02:57+0000",
       "id": "624510964324764_1046909755418214"
    },
  ]
}

这个数据片段叫JSON, 这是在智能手机上看到的一个Facebook的一个状态消息，来自于 Facebook API，是不是相当简洁？

现象一下，如果你是一个负责这个API的Facebook工程师，突然你有一天你脑子一热决定把id字段改成message_id. 可以想象，这么一个小小的改动，有可能让Facebook崩溃。最终导致所有依赖之前结构的设备不能收集和展示给用户内容，这是多么操蛋的一天。

好的，糟糕的和丑陋的（The good, the bad and the ugly）

一个糟糕的API设计早晚会引起问题：

缺乏一致性:一旦一个API的增长,要创建访问点往往只是为了满足紧急需求。
很难扩展：遇到问题很难找到扩展突破口。
很难学习：学习曲线陡峭
性能问题：后来适配的API往往是性能瓶颈
API改变无休止： 总是第一次是对的，后面都不对。

API是程序和用户之间的契约，当突然改变的时候不能引起混乱，这个契约要有远见。这是设计的入口：一个计划，一个公约，一个系统或者是一个可评估的交流。

原文

API Design: Think First, Code Later