在为基于社区的网站构建API之前,开发人员应该了解什么？

在开始繁重编码之前,开发人员应该为基于社区的网站设计和实现API知道什么？有许多API,如Twitter API,Facebook API,Flickr API等,这些都是很好的例子.但是,您将如何构建自己的API？

你会用什么技术？我认为使用类似REST的接口是个好主意,这样可以从不同的平台/客户端/浏览器/命令行工具(如curl)访问API .我对吗？我知道应该满足Web开发的所有原则,如缓存,可用性,可伸缩性,安全性,防止潜在DOS攻击,验证等.当涉及到API时,一些最重要的事情是向后兼容性和文档.我错过了什么吗？

另一方面,从用户的角度思考(我的意思是将要使用您的API的开发人员),您会在API中寻找什么？好的文件？大量的代码示例？

这个问题的灵感来自Joel Coehoorn的问题"开发人员在建立公共网站之前应该知道什么？" .

这个问题是一个社区wiki,所以我希望你能帮助我在为一个基于社区的网站构建API时应该解决的所有问题.

如果您确实要定义REST API,请执行以下操作:

忘记HTTP和媒体类型以外的所有技术问题.

确定客户端将与API交互的主要用例

编写针对假设的HTTP服务器执行这些"用例"的客户端代码.客户端应该开始的唯一信息是从GET请求到根API URL的响应.客户端应该从HTTP内容类型标头中识别响应的媒体类型,它应该解析响应.该响应应包含指向允许客户端执行所有API所需操作的其他资源的链接.

在创建REST API时,更容易将其视为机器的"用户界面",而不是公开对象模型或流程模型.想象一下,机器通过检索响应,跟踪链接,处理响应和跟随下一个链接,以编程方式导航api. 客户端永远不应该基于其对服务器如何组织资源的了解来构造URL.

如何格式化和识别这些链接至关重要.在您将定义REST API做出最重要的决定是你的媒体类型的选择.您需要找到表示链接信息的标准方法(想想Atom,微格式,原子链接关系,Html5链接关系),或者如果您有特殊需求,并且您不需要真正广泛覆盖许多客户,那么您可以创建你自己的媒体类型.

记录这些媒体类型的结构以及它们可能包含的链接/链接关系.有关媒体类型的特定信息对客户至关重要.让服务器返回Content-Type:application/xml对于客户端来说是没用的,如果它想要做任何事情而不是解析响应.客户端无法知道application/xml类型的响应中包含的内容.有些人确实相信你可以使用XML模式来定义它,但是这有一些缺点,它违反了REST"自描述消息"约束.

请记住,URL的外观与客户端的运行方式完全无关.唯一的例外是媒体类型可以指定模板化URI的使用,并可以定义这些模板的参数. 在选择服务器端框架时,URL的结构将变得非常重要.服务器控制URL结构,客户端不应该在意.但是,不要让服务器端框架规定客户端如何与API交互,并且在选择需要您更改API的框架时要非常谨慎. HTTP应该是关于客户端/服务器交互的唯一约束.