如何在 API 设计上彻底失败

原文：https://medium.com/hackernoon/how-to-completely-fail-at-api-design-6b1dc9ae27f6

API 设计是一个困难的话题。很多人对此有自己的看法，而且几乎所有有看法的人都是不该问的人。既然您正在阅读一篇关于 API 的文章，那么可以相当有把握地假设您至少已经对它有了一些看法。您可能是来阅读我关于 GraphQL 或 REST 或类似主题的文章的，但是我会让您失望的。

事实上，如果你试图弄清楚是否应该构建一个 GraphQL 或 REST API，而你还没有回答一个简单的问题，那么你已经在构建正确的 API 的路上失败了。你本末倒置了，当你意识到推车应该是一架飞机时，你的马就会死掉。如果你不想成为一个杀马贼，抛开我刚才说你失败的事实，请考虑一下这个问题。

这个问题

你应该回答的 API 设计的第一个问题是:

API 应该支持构建一个功能完整、外观更好的用户界面版本吗？

请思考一下这个问题。如果你是一个 API 开发者，你可能听说过一些公司在他们的 API 中增加了限制性的权限或者限制，使得在某人已经开发了一个更好的应用或者网站之后，再开发一个客户端是不可能的。如果你不是开发人员，那么你可能听说过关于 X 公司“封锁第三方开发人员”或“关闭 ABC 其他服务”或“在公共场合意外杀死一匹马”的不祥故事(当然是比喻)。不管你属于这两个阵营中的哪一个，希望我们都同意，你不想为你的公司发生这样的事情负责。

这里的失败是在某个时候将这个问题的答案从“是”改为“否”。如果您回答“是”,表示您希望让其他人在构建您自己的应用程序方面比您做得更好，这很好。如果你回答“不”,你希望你的用户为了他们的主要体验而留在你的网站上，那也没问题。但是如果你今天回答“是”,明天成功后又回答“不是”,那么你就在一场疯狂的旅程中。甚至可能糟糕到被商人或者股东/风投发现。因此，错误地回答这个问题可能会付出真正的代价。

无知不是借口

对于外面的商人，我有一些事情要告诉你。如果你去找一个开发者，告诉他们“为我们的产品做一个 API”，而没有任何明确的说明或限制，那么他们已经为你回答了这个问题，他们的回答几乎肯定是“是”

正如我所说的,“是”可能是这个问题的一个完全正确的答案，但前提是你对它的含义有所准备。想象一下，你最疯狂的幻想已经实现了(关于你的产品…保持干净，人们)。你的产品漂亮、时尚且易于使用。您会看到一个用户在 it 部门前完成工作。当他们想要保存时，他们不会意外地点击删除按钮，他们不会错过他们想要点击的小部件，即使它就在那里，而且整个过程非常漂亮和快速。现在想象一下，那个人使用的界面不是你们公司制造的。当然，它在底层使用你的服务，但是互联网上某个你甚至从未听说过的随机的人制作了那个接口，它比你和你的开发团队每天都在烦恼的那个要好。

你开心吗？你的老板会开心吗？

再说一次，“是”是一个非常有效和非常可爱的答案。如果这就是你的答案，太好了。你已经有了一个能完成工作的产品，一个能让开发人员与你的公司合作的 API，还有那些有兴趣投入自己的时间来做这件事的人。吃一顿长长的午餐，享受你的一天。

但是很多商人会被这种情况吓到并感到不安。如果你对这种情况的第一反应是“一定有什么方法可以关闭它！”那么你的答案是“不”，你需要知道这一点。你的开发者需要知道这一点。例如，如果你的业务是基于在你的界面中销售广告，你可能有一个非常重要的理由让你的用户在你的界面中，而不是在其他地方。

如果你发现自己处于不得不将答案从“是”转换为“否”的尴尬境地，这将意味着告诉那些对你的产品非常感兴趣的人，他们不能用你的产品做到这一点。这意味着你必须告诉那些真正优秀的、感兴趣的、可能是付费的用户，他们的努力是不被需要的。如果你在这一点上足够受欢迎，它甚至可能会以“镇压”、“封锁”和“无法形容的马暴力”等短语成为新闻，而你真的不想这样。

好的，明白了

非常好。如果这个问题的答案是“是”,你可以继续用谷歌搜索 GraphQL vs REST。如果答案是否定的，那么你还有一堆其他的问题要回答，比如你的 API 应该做什么，为什么你需要一个 API，等等。你可以解决所有这些问题，做出适合你和你的用户的东西。如果你能清楚地回答这些问题，那么你的法律团队将写出正确的条款和条件，你的开发者将构建正确的 API 等等。你的用户可能仍然想要更多的访问，但这现在是一个功能请求，而不是一个记者要求你评论你为什么对你的客户如此刻薄。

如果你是一名开发人员，有人让你做一个 API，那么考虑一下他们是否已经回答了这个问题。如果你怀疑他们没有，把他们指在这里或者问问你自己来确认一下。

仍然有大量的工作要做，但是如果你已经思考并回答了这个问题，那么你就没有在起跑线上失败，只有在你变得足够受欢迎以至于人们注意到你之后，你才有希望避免意识到你在 API 设计上失败的痛苦。

原载于 2017 年 4 月 7 日[【www.scorpionresponse.com】](https://www.scorpionresponse.com/posts/2017/04/how-to-completely-fail-at-api-design/)。