Web API设计的5条黄金法则

本文概述

透视
规则1：文档
规则2：稳定性和一致性
规则3：灵活性
规则4：安全性
规则5：易于采用
Web API总结

是否曾经发现自己想知道”他们在想什么？”通过其API集成Web服务时？如果没有, 那你比我幸运得多。

任何软件开发人员都知道它是多么容易让一个项目退化为面条代码和Web API是没有不易产生了错综复杂的。但这不是必须的。实际上, 可以设计人们实际上会喜欢使用的出色Web API, 并且你也会喜欢创建它们。但是如何？这个问题的答案的问题是这个职位是什么一回事。

透视

在大多数情况下, 当你构建解决方案时, 你都是为非程序员或技术水平不高的最终用户设计的。你为他们提供了图形界面, 如果你做得对, 可以从他们那里了解他们需要界面做什么的一个很好的主意。

但是API开发是不同的。你正在为程序员设计一个界面, 可能甚至不知道他们是谁。无论他们是谁, 他们都将具有技术上的先进性(或者至少会认为他们具有技术上的先进性)来指出软件中的每个小缺陷。你的用户可能对你的API的批评程度与对他们的API的批评程度一样, 并会充分享受对其的批评。

顺便说一下, 这就是讽刺的一部分。如果有人应该了解如何制作易于使用的网络API, 那就是你自己。毕竟, 你就像API用户一样都是软件工程师, 因此你可以分享他们的观点。是不是

好吧, 尽管你确实了解他们的观点, 但不一定分享他们的观点。在开发或增强API时, 你具有API设计人员的观点, 而他们具有API用户的观点。

API设计人员通常关注”该服务需要做什么？”之类的问题。或”此服务需要提供什么？”, 而API用户则专注于”如何使用此API来完成我需要做的事情？”, 或更准确地说, “我如何花最少的精力来获得什么？我需要使用该API吗？”。

这些不同的问题导致两种截然不同的观点。因此, 设计出色的API的必要先决条件是将你的观点从API设计者的观点转变为API用户的观点。换句话说, 不断问自己自己是你自己的用户时会自然要问的问题。与其考虑你的API可以做什么, 不如考虑它可能需要或想要使用的不同方式, 然后集中精力使API用户的任务尽可能简单。

尽管这听起来似乎很容易而且很明显, 但令人惊讶的是, 如此频繁地设计API的方式似乎很少。考虑一下你在职业生涯中遇到的API。考虑到这种观点, 设计它们的频率是多少？ Web API设计可能具有挑战性。

因此, 让我们继续讨论设计优秀Web API的5条黄金规则, 即：

文献资料
稳定性和一致性
灵活性
安全
易于采用

相关：使用REST规范从未做过的5件事

规则1：文档

文档。是的, 我从这里开始。

你讨厌文件吗？好吧, 我很同情, 但是戴上”用户视角”帽子, 我敢打赌, 除了必须编写文档之外, 你最讨厌的一件事就是必须尝试使用未记录的API。我休息一下

底线是, 如果你希望任何人使用你的API, 则文档必不可少。你只需要正确解决这个问题即可。这是用户首先看到的东西, 因此在某些方面就像礼物包装一样。呈现的很好, 人们更有可能使用你的API并忍受任何特质。

那么我们如何编写好的文档呢？

相对容易的部分是记录API方法本身。即示例请求和响应, 以及两者中每个元素的描述。幸运的是, 有越来越多的软件工具可以简化和简化生成文档的任务。或者, 你可以自己编写一些可以对你的API, 端点和函数进行内部检查的东西, 并为你生成相应的文档。

但是, 将出色的文档与足够的文档区分开来的是, 包含了使用示例以及理想的教程。这可以帮助用户了解你的API以及从何处开始。它可以定向它们并帮助它们将你的API加载到他们的大脑中。

例如, 如果Twilio的开发人员列出了他们的API的每个类, 每个方法以及每个可能的响应, 但你不必费心说可以通过它发送SMS, 跟踪电话或购买电话号码他们的API, API用户要花很长时间才能找到该信息并连贯地理解它。你能否想象通过一棵巨大的类和方法树进行排序, 而不对它们的用途(名称)有任何了解？听起来很糟糕吧？但这正是许多API提供程序所做的事情, 从而使除自己以外的任何人都看不到他们的API。 Rackspace CloudFiles开发人员和API指南就是这样的一个例子。除非你已经了解了他们的工作和所提供的东西, 否则很难掌握自己的方向。

因此, 编写简洁的教程可以帮助开发人员快速启动并运行, 至少要了解他们正在尝试做的事情, 然后将它们指向更详细的, 有完整文档的功能列表的方向, 以便他们可以扩展关于他们所拥有的。

处理完文档后, 请务必确认它对你本人以外的其他人有意义。将其发送给你网络中的其他开发人员, 除了给他们指向文档外, 不给他们任何指导, 并要求他们遵循教程或在15分钟内完成一些真正基础的工作。如果他们在15分钟之内无法与你的API进行基本集成, 那么你还有更多工作要做。

有关出色和详细文档的一些值得注意的示例, 请查看Twilio, Django和MailChimp。这些产品都不一定是市场上最好的产品(尽管它们都是好产品), 但它们通过在市场中提供一些最佳文档来区分主题本身, 这无疑促进了它们的广泛接受度和市场份额。

规则2：稳定性和一致性

如果你曾经使用过Facebook的API, 那么你就会知道他们不赞成使用和完全重写他们的API的频率。无论你多么尊重他们的黑客文化或产品, 他们的观点都不对开发人员友好。他们仍然成功的原因是因为他们拥有十亿用户, 而不是因为他们的API很棒。

但是你可能没有这么庞大的用户群和市场份额, 因此你将需要一个不稳定的API, 要长时间保持运行和支持旧版本。甚至几年。为此, 这里有一些提示和技巧。

举例来说, 你可以通过网址http://myapisite.com/api/widgets访问你的API, 并以JSON格式提供其响应。虽然乍一看似乎不错, 但是当你需要修改JSON响应的格式时会发生什么呢？已经与你整合在一起的每个人都会崩溃。哎呀

因此, 请提前做一些计划, 并从一开始就对API进行版本控制, 明确将版本号合并到URL中(例如, http://myapisite.com/api/widgets?version=1或http://myapisite.com/api / widgets / v1), 以便人们可以依靠版本1正常工作, 并可以在准备就绪时升级到任何后续版本。如果你需要在某个时候逐步淘汰先前版本, 请继续进行, 但要多加注意并提供某种过渡计划。

一个好的URL方案将在URL中包含主要版本。输出格式或受支持的数据类型的任何更改都应导致升级到新的主要版本。通常, 如果你所做的只是向输出中添加键或节点, 则可以保留相同的版本, 但是为了安全起见, 只要输出发生变化, 就可以保留一个版本。

除了长期稳定之外, API还必须在内部保持一致。我已经看到许多API, 这些API会根据所使用的端点来更改参数名称或POST数据的方法。相反, 你应该在API中全局处理通用参数, 并使用继承或共享体系结构在整个API中重复使用相同的命名约定和一致的数据处理。

最后, 你需要记录并发布变更日志以显示API版本之间的差异, 以便用户确切知道如何升级。

相关：Grape Gem教程：如何在Ruby中构建类似REST的API

规则3：灵活性

垃圾回收, 垃圾回收(GIGO)是大多数程序员都熟知的口头禅。当应用于Web API设计时, 该指导原则倾向于规定一种相当僵化的方法来请求验证。听起来不错吧？没有混乱, 没有问题。

然而, 与所有事物一样, 需要保持一定的平衡。由于无法预期用户将要使用你的服务的所有方式, 并且由于并非每个客户端平台都是一致的(即, 并非每个平台都具有非常好的JSON支持, 不错的OAuth库等), 因此在输入和输出约束方面至少具有一定程度的灵活性或容忍度。

例如, 许多API将支持多种输出格式, 例如JSON, YAML, XML等。 , 但仅支持在URL本身中指定格式。本着保持灵活性的精神, 你可以允许在URL中指定此名称(例如/api/v1/widgets.json), 或者你也可以阅读并识别Accept：application / json HTTP标头, 或支持querystring变量, 例如？format = JSON, 等等。

而在我们讨论的同时, 为什么不让指定的格式不区分大小写, 以便用户也可以指定？format = json？这是减轻API用户不必要的烦恼的经典示例。

另一个例子是允许输入变量的不同方式。因此, 就像你有多种输出格式一样, 也允许多种输入格式(例如, 纯POST变量, JSON, XML等)。你至少应该支持标准POST变量, 并且许多现代应用程序也支持JSON, 因此这两个是一个不错的起点。

这里的重点是, 你不应该假设每个人都共享你的技术偏好。通过对其他API的工作方式进行一些研究, 并通过与其他开发人员的对话, 你可以搜集有用的其他有价值的替代方法并将其包含在API中。

规则4：安全性

安全显然是构建到Web服务中最重要的事情之一, 但是许多开发人员使它难以使用。作为API提供者, 你应该提供有关访问API时如何进行身份验证和授权的可用示例。最终用户要花费数小时进行工作, 这应该不是一个困难的问题。将你的目标设为他们不必编写任何代码, 或者使他们花费不到5分钟的时间来编写代码。

对于大多数API, 我更喜欢基于令牌的简单身份验证, 其中令牌是分配给用户的随机哈希, 如果令牌被盗, 他们可以在任何时候重置它。允许令牌通过POST或HTTP标头传递。例如, 用户可以(并且应该)将SHA-1令牌作为POST变量或作为标头发送, 格式为”授权：da39a3ee5e6b4b0d3255bfef95601890afd80709″。

另外, 请选择安全令牌, 而不是短数字标识符。不可逆转的东西是最好的。例如, 在用户创建期间仅生成SHA令牌并将其存储在数据库中相对简单。然后, 你可以简单地在数据库中查询与该令牌匹配的所有用户。你也可以使用唯一标识符和盐值生成令牌, 例如SHA(User.ID +” abcd123″), 然后查询是否有任何匹配的用户。例如, 其中TokenFromPost = SHA(User.ID +” abcd123″)。

另一个非常好的选择是OAuth 2 + SSL。无论如何, 你都应该使用SSL, 但是OAuth 2在服务器端实现起来相当简单, 并且库可用于许多常见的编程语言。

如果应该通过JavaScript在公共网站上访问你制作的API, 则还需要确保验证每个令牌的帐户URL列表。这样, 没有人可以检查对你的API的调用, 从用户那里窃取令牌并自行使用。

还有一些其他重要的事情要牢记：

将功能列入白名单。 API通常允许你对数据执行基本的创建, 读取, 更新和删除操作。但是, 你不想对每个实体都允许执行这些操作, 因此请确保每个实体都有允许操作的白名单。例如, 请确保只有授权用户才能运行/ user / delete / <id>之类的命令。同样, 用户要求中发送的所有有用标头也需要根据白名单进行验证。如果允许Content-type标头, 请验证用户发送的内容是否确实与支持的内容类型的whilelist匹配。如果不是, 则发回错误消息, 例如406 Not Acceptable响应。白名单很重要, 因为许多API是自动生成的, 或者改用黑名单, 这意味着你必须明确说明不需要的内容。但是, 安全的黄金法则是从一无所有开始, 仅明确允许你想要的东西。
保护自己免受跨站请求伪造(CSRF)的侵害。如果你允许会话或cookie身份验证, 则需要确保自己免受CSRF攻击。开放式Web应用程序安全项目(OWASP)提供了有关如何消除这些漏洞的有用指导。
验证对资源的访问。在每个请求中, 你都需要验证是否确实允许用户访问他们所引用的特定项目。因此, 如果你有一个端点可以查看用户的信用卡详细信息(例如/ account / card / view / 152423), 请确保ID” 152423″引用的是用户真正有权访问的资源。
验证所有输入。来自用户的所有输入都需要安全地进行解析, 如果使用的是复杂的输入(例如XML或JSON), 最好使用众所周知的库。不要建立自己的解析器, 否则你将遭受重创。

规则5：易于采用

这实际上是最重要的规则, 它是建立在所有其他规则之上的。正如我在文档规则中提到的那样, 请尝试使用API的新手。确保它们可以在几分钟之内启动并运行至少API的基本实现, 即使它只是按照教程进行。我认为15分钟是一个不错的目标。

以下是一些特定的建议, 以简化和促进API的采用：

确保人们可以实际使用你的API, 并且每次都可以第一次使用它。让新手偶尔尝试实施你的API, 以验证它不会以某种使你难以理解的方式引起混淆。
把事情简单化。不要进行任何精美的身份验证。不要做一些疯狂的自定义URL方案。不要重新发明SOAP, JSON, REST或其他任何东西。使用已经可以实现并被广泛接受的所有工具, 以便开发人员只需学习你的API, 而不必学习你的API + 10种晦涩的新技术。
提供特定于语言的库以与你的服务接口。有一些不错的工具可以自动为你生成一个库, 例如Alpaca或Apache Thrift。目前, Alpaca支持Node, PHP, Python和Ruby。 Thrift支持C ++, Java, Python, PHP, Ruby, Erlang, Perl, Haskell, C＃, Cocoa, JavaScript, Node.js, Smalltalk, OCaml, Delphi等。
简化任何必要的注册。如果你不是在开发开源API, 或者有任何形式的注册过程, 请确保在注册后立即将用户定向到教程。并使注册过程完全自动化, 而无需你进行人工干预。
提供出色的支持。采纳的最大障碍是缺乏支持。你将如何处理和响应错误报告？不清楚的文档呢？单纯的用户？论坛, 错误跟踪器和电子邮件支持都是不错的开始, 但是请确保当有人发布错误时, 你能真正解决它。没有人希望看到鬼城论坛或未解决的大量错误。