#api#practice

api.md

资料来源

• How We Design Our APIs at Slack - Slack Engineering

考虑的事情

• 做一件事情，并把它做好
• Make it fast and easy to get started
• 努力实现直觉上的一致性
  • 反映在你的URL，输入和输出响应中。开发人员应该能够猜到你的API的部分内容，即使不看文档。
  • 与工业标准的一致性。它应该尽可能地遵守行业中公认的最佳实践。
  • 与你的产品保持一致。你应该根据你在产品中对这些概念的称呼来选择字段名。避免使用缩写、首字母缩写和行话。要啰嗦。
  • 与你的其他API方法保持一致。你在不同的API方法中使用的名称应该相互一致。
  • 实现一致性的最好方法之一是巩固和写下你对API设计的意见，特别是当没有单一的正确或错误的方法时。选择一个方向并坚持下去。
  • 在Slack，我们写下了全面的API设计指南，定义了我们的API所遵循的一贯做法和模式。
• 设计API的另一个原则是返回有意义的错误，使开发人员更容易排除故障。
  • 不正确或不明确的错误是令人沮丧的，并且会对你的API的采用产生负面影响。
  • 它们会帮助开发者理解问题以及如何解决它。实施细节不应该在你的API中泄漏，特别是错误。
  • 除了返回错误代码外，在文档中或API响应中的其他地方添加较长的错误，通常是有用的。这些可以包括对错误的可读描述，包括如何解决这个问题或链接到更多信息。
• 为伸缩性和扩展考虑
  • 对大的集合进行分页。很多时候，API需要处理大型数据集。一个API调用可能最终会返回成千上万的项目。这可能会使网络应用程序的后端过载，甚至会使不能处理大数据集的客户端变慢。出于这个原因，对任何大的结果集进行分页是很重要的。
  • 不要将大集合嵌套在其他大集合中。在这种情况下，分页就太复杂了。
  • 对API限流 你不希望一个行为不端的开发者或失控的代码循环使你的应用程序崩溃。