我们正在推出一个新的REST API,我想要一些关于如何格式化输入参数的最佳实践的社区意见:
现在,我们的API非常以JSON为中心(仅返回JSON).关于我们是否想要/需要返回XML的争论是一个单独的问题.
由于我们的API输出是以JSON为中心的,我们一直在走一条路,我们的输入有点以JSON为中心,我一直在想这可能对某些人来说很方便,但总的来说很奇怪.
例如,要获得一些产品详细信息,我们可以立即提取多个产品:
http://our.api.com/Product?id=["101404","7267261"]
我们应该简化为:
http://our.api.com/Product?id=101404,7267261
或者有JSON输入方便吗？更多的痛苦？
我们可能希望接受这两种风格,但这种灵活性是否会导致更多的混乱和头痛(可维护性,文档等)？
更复杂的情况是我们想要提供更复杂的输入.例如,如果我们想在搜索上允许多个过滤器:
http://our.api.com/Search?term=pumas&filters={"productType":["Clothing","Bags"],"color":["Black","Red"]}
我们不一定要将过滤器类型(例如productType和颜色)作为请求名称,如下所示:
http://our.api.com/Search?term=pumas&productType=["Clothing","Bags"]&color=["Black","Red"]
因为我们想要将所有过滤器输入组合在一起.
最后,这真的很重要吗？可能有很多JSON实用程序,输入类型并不重要.
我知道我们的JavaScript客户端对API进行AJAX调用可能会欣赏JSON输入以使他们的生活更轻松.