经过六个月的艰苦会议、精心编码和耐心的QA测试，API终于准备发布。感到无比自豪，但几个月后，整个项目在眼前崩溃，不得不关闭。没有高层的变动，也没有战略上的转变，而是没有人愿意使用API。尽管进行了长时间的会议、精心的编码和残酷的测试，但忘记了一个细节：在尝试构建API之前，忘记了设计它，并在设计周期中包括实际用户。
在急于构建面向外部的API并将其交到客户手中时，公司忘记了“销售”任何产品或服务的黄金法则：了解客户的需求。
当询问其他公司为何要构建API时，最常见的回答是“他们希望将应用程序/数据暴露给开发者。”但当询问“为什么”时，答案似乎不够充分，并不是因为他们没有提供很好的服务，而是因为他们没有花时间理解或考虑开发者的使用案例。
在构建API之前，重要的是要理解为何要构建API。重要的是要理解为谁构建——是内部使用、客户，还是将扩展服务/补充他们自己的开发者？是为了数据迁移还是服务利用？API用户将期望进行哪些类型的操作？
这意味着要进一步了解，而不仅仅是说“他们将使用数据”，而是要绘制一个资源图，显示开发者将使用哪些确切的服务，以及他们将如何使用它们。这很容易与CRUD的实现混淆——试图将这些操作连接到GET、POST、PUT、PATCH和DELETE。但这个过程应该更简单，因为在这个阶段，只是在创建用户故事，而不是技术定义。因此，不要专注于CRUD，而是关注客户将能够做什么，例如API能够创建新用户、更新用户、重置忘记的密码等。或者如果有一个消息系统，能够发送消息、创建草稿、发送草稿、查看消息、将消息移动到文件夹、查看联系人等。
在这个阶段，确保让用户参与进来。询问他们想要做什么，什么对他们来说很重要。因为无论API设计多么周到，或者编码得多么仔细——如果它不是他们想要的，它就不会对有任何好处。
一旦有了API用户需求，现在就是设计API的时候了。令人惊讶的是，许多公司跳过了这一步，而是直接进入开发阶段。问题是，API是一份合同，是和用户之间的协议。这是公司对他们的承诺，他们依赖API不仅使他们的生活更轻松，而且也是他们生计的一部分。当破坏向后兼容性，当改变事情时，正在剥夺他们专注于开发新功能的能力，迫使他们专注于修复由API造成的问题。
因此，重要的是要确保API设计为API的初始发布以及未来开发提供了坚实的基础。重要的是API设计要专注于长期会发生什么。不要只关注当前的产品路线图，还要考虑产品在2-3年后可能在哪里——以及API将需要能够做什么。
做到这一点的最简单方法之一是利用Spec Driven Development，或者通过设计和开发两个不同的阶段来构建API。
第一阶段，设计阶段意味着与开发团队和潜在的API用户合作，制定一个规范，或者一个API应该如何工作的蓝图。有几个规范可以帮助做到这一点，包括RAML、Swagger和API Blueprint。个人最喜欢的是RAML，因为它提供了一个单一的格式来管理API（YAML），并允许代码重用，同时鼓励模式驱动的设计。RAML还有一些很棒的开源项目，包括一个API设计器，它在定义API时以视觉方式显示API，交互式文档，以及一个API笔记本，让用户可以使用JavaScript与API互动和探索。
使用MuleSoft的免费托管API设计器，还可以原型化或模拟API，让能够立即收集用户反馈，而无需编写或更改任何代码。在设计过程中原型化/模拟API至关重要，因为它可以帮助识别潜在的设计缺陷和不一致性，同时让未来的API开发者为提供宝贵的反馈和可能没有想到的使用案例。
Spec Driven Development的第二阶段是开发，或编写API不同层的代码。通过拥有一个强大的蓝图供开发人员使用，他们可以快速且无畏地构建API，不必担心他们的资源是否会与其他开发人员的资源一起工作，或者模式是否匹配。
这个想法是，在设计阶段，将消除99%的设计缺陷/潜在设计错误。因此，在开发周期中坚持规范非常重要。很容易想要偏离或改变事情，但这样做会让回到起点——在没有事先仔细考虑的情况下即兴创建API。记住，擅长短期设计，但在长期设计上却很糟糕，而API旨在长期存在。
如果确实发现设计上有问题，那没关系。这只是意味着需要回到设计阶段，实施解决方案，然后测试它，以确保该解决方案按照用户预期的方式工作，并且不会破坏任何其他东西/引起任何不一致性。一旦这样做了，可以立即回到开发阶段。