在开始大量编码之前，开发人员应该为基于社区的网站设计和实现API知道什么？有很多API，例如Twitter API，Facebook API，Flickr API等，这些都是很好的例子。但你怎么会build your own API？
您会使用哪些技术？我认为使用REST之类的界面是个好主意，这样可以从不同的平台/客户端/浏览器/命令行工具（如curl）访问API。我对吗？我知道应该满足Web开发的所有原则，如缓存，可用性，可伸缩性，安全性，防止潜在DOS攻击，验证等。当涉及到API时，一些最重要的事情是向后兼容性和文档。我错过了什么吗？
另一方面，从用户的角度考虑（我的意思是将要使用您的API的开发人员），您会在API中寻找什么？好的文件？大量的代码示例？
这个问题的灵感来自于Joel Coehoorn的问题"What should a developer know before building a public web site?"。
这个问题是一个社区维基，所以我希望您能帮助我在为基于社区的网站构建API时应该解决所有问题。
答案 0 :(得分：40)
如果您确实要定义REST API，请执行以下操作：
忘记 HTTP和媒体类型以外的所有技术问题。
确定客户端将与API交互的主要用例
编写针对假设的HTTP服务器执行这些“用例”的客户端代码。客户端应该开始的唯一信息是从GET请求到根API URL的响应。客户端应该从HTTP内容类型标头中识别响应的媒体类型，它应该解析响应。该响应应包含指向允许客户端执行所有API所需操作的其他资源的链接。
创建REST api时，更容易将其视为机器的“用户界面”，而不是公开对象模型或流程模型。想象一下，机器通过检索响应，跟踪链接，处理响应和跟随下一个链接，以编程方式导航api。 客户端绝不应根据其对服务器如何组织资源的了解来构建URL 。
如何格式化和识别这些链接至关重要。您在定义REST API时最重要的决定是您选择的媒体类型。您需要找到表示该链接信息的标准方式（考虑Atom，microformats，atom link-relations，Html5 link relations）或者您是否有特殊需求而不需要非常广泛地覆盖许多客户，然后您可以创建自己的media-types。
记录这些媒体类型的结构以及它们可能包含的链接/链接关系。有关媒体类型的特定信息对客户至关重要。让服务器返回Content-Type：application / xml对于客户端来说是没用的，如果它想要做任何事情而不是解析响应。客户端无法知道application / xml类型的响应中包含的内容。有些人确实相信你可以使用XML模式来定义它，但是这有一些缺点，它违反了REST“自我描述性消息”约束。
请记住，URL的外观与客户端的运行方式完全无关。唯一的例外是媒体类型可以指定模板化URI的使用，并可以定义这些模板的参数。 在选择服务器端框架时，URL的结构将变得非常重要。服务器控制URL结构，客户端不应该在意。但是，不要让服务器端框架规定客户端如何与API交互，并且在选择需要您更改API的框架时要非常谨慎。 HTTP应该是有关客户端/服务器交互的唯一约束。