Web services 接口设计/API设计：通用方法与特定方法

我们目前正在考虑如何为其他系统设计接口

我的同事希望实现一个通用接口（例如doIt（JSONArray）），在该接口中，您可以将希望执行的信息放在JSONObject中，以便调用如下所示：

doIt（“{”方法“：“getInformation”，“id:“1234”，“detailLevel:“2”}”）

doIt（“{”方法“：“getEmployeeInfo”，“EmployeeId:“4567”，“公司“：“Acme Inc.”}”）

（在本例中，我使用“and”只是为了演示。我知道我必须在实际系统中避开“and”）。 然后可以通过http访问此方法，因此我希望

http://mysite/doIt?parm={JSONObject}

我的方法是使用不同的接口及其各自的参数，这样我就有了一个

getInformation（1234,2）

和

getEmployeeInfo（4567，“Acme Inc.”

接口。因此，对于通过http进行访问，我的方案如下：

http://mysite/getInformation?id=1234&detailLevel=2

和

http://mysite/getEmployeeInfo?employeeId=4567&company=acmeinc.

对于访问我们服务的客户，我们希望提供封装bevahiour的特殊库。例如，将有一个客户端java库，它将客户端调用getEmployeeInfo（..）转换为

http://mysite/doIt?parm={'{"method":"getEmployeeInfo", "EmployeeId":"4567", "company": "Acme Inc."}'}

或

http://mysite/getEmployeeInfo?employeeId=4567&company=acmeinc.

然后返回结果

因此，对于客户端来说，如果他们使用处理“翻译”的库，那么后端的工作方式将是完全透明的

---

你认为每个想法的利弊是什么？我更喜欢我的方法，因为它看起来“更干净”。但这只是一种难以争辩的感觉。也许你可以给我（或他）一些关于设计的想法，也可以触及一些领域（可伸缩性、安全性等），或者提供关于这个问题的有用链接，JSON解决方案可能会更好，因为你可以更容易地发送复杂的对象

---

但这里只是一些语法细节，让老板选择（或投票）并构建您的软件。

我可能会投票支持JSON解决方案，即使它们或多或少是等效的。（都是易于扩展、标准、经得起未来考验的解决方案。）

选择JSON的原因如下：

• 对于不同的平台，有大量不同的库可以帮助您构建正确的对象，检查字符串数据是否有效，等等

• 将JSON数据解组为对象。一些库（例如）可以自动将JSON封送和解封送到对象中。避免您编写自己的代码，并且您可以从使用已由他人测试的代码中获益

• 支持新接口。假设您将传输方法更改为套接字、ftp（！）或其他方式。您仍然可以使用另一个传输将JSON对象发送到后端

---

我意识到这个问题由来已久，但我认为这里的答案会引导开发人员走上错误的道路
根据我的经验，你应该总是倾向于更具体的方法。泛型方法很难测试，很难理解，而且不提供（或很少）IDE/编译器支持。您描述的这样一个api并没有告诉用户它将做什么
您自己建议的api设计要好得多

---

尽管如此，这是一种平衡行为
老板不在乎，只要它能工作，而且是经得起未来考验的；）好的，但是如果API应该从另一个客户端（例如javascript web浏览器）使用呢。您不认为首先构建JSON对象然后将其发送到服务器更“困难”吗？在另一种情况下，您只需在url/post请求中输入值（这并没有太大的区别..我知道。）或者您无法使用此版本进行RESTful访问（我的版本也不是RESTful，但您可以想象类似于（但我并不认为这有什么好处……JSON是JavaScript对象表示法的缩写，因此使用JavaScript web浏览器肯定不会有问题；）而且，构建JSON对象并不困难。