我感兴趣的是不同语言用户(我们可能会向使用多种平台的人提供API,特别是包括 .NET、Java、ActionScript 和 JavaScript 的人)对您认为好的Web API示例的意见以及您的良好体验。
一些要点如下: 1. 您更喜欢SOAP类型的服务还是REST/RPC样式的服务?我怀疑具有平台支持(例如.NET,Java)的人会更喜欢SOAP,而使用没有平台支持的语言的人则更喜欢其他服务,但我想验证这个假设。 2. 您是否关心API实际上是RESTful还是一个普通的RPC样式的HTTP GET/POST?如果是,为什么关心?一个API是否正确描述自己更重要(即不要声称自己是RESTful而实际上是RPC样式),而不是它实际上是两者之一? 3. 我们需要验证谁在使用服务。我一直在研究Amazon S3身份验证,它使用公共标识符和一个私有令牌来将请求的参数散列成验证令牌(这也类似于flickr)。您以前使用过这种身份验证吗?您如何处理它?有没有哈希算法您认为有问题(即不受您所使用平台支持)?您更喜欢在HTTP头中发送哈希还是在URI中?
版本控制应该如何处理?设置类似于 /v1/
的子目录以便未来可以添加新版本是否是一个好主意,或者您会采取不同的方式,比如将版本放在请求有效负载或查询中?您期望构建API的版本能够得到支持多长时间(即如果引入了v2,那么v1的生命周期预期是多少)。
此外,任何其他观点和需要覆盖的内容都将很有用。
我故意在实际实现的API类型上保持模糊,因为我正在寻求关于人们认为什么是好的API和实现机制的一般指导,因此这篇文章及其答案将对未来更多的人有用。
注意:我已经进行了搜索,但找不到与此相关的通用问题-它们似乎都针对某种类型的API-但如果它是重复的,请告诉我。另外,如果它应该是社区维基(我认为人们应该得到回答的信用,所以我没有将其设为社区维基),请让我知道,我会将其更改为社区维基。