Interface Design / API Design: Generic method vs specific methods

we are currently thinking about how to design an interface for other systems.

My co-worker would like to implement a generic interface (for e开发者_运维问答.g. doIt(JSONArray)) where you put the desired information you would like to do inside a JSONObject, so that calls would e.g. look like this: doIt('{"method":"getInformation", "id":"1234", "detailLevel": "2"}') doIt('{"method":"getEmployeeInfo", "EmployeeId":"4567", "company": "Acme Inc."}')

(i used ' and " in this example just for demonstration purposes. I know that i had to escape the " in the real system). This method will then be accessable via http, so that i would like http://mysite/doIt?parm={JSONObject}

My approach is to use different interfaces with their respective parameters so that I would have a getInformation(1234,2) and a getEmployeeInfo(4567,"Acme Inc.") interface. So for access via http my scheme would look like: http://mysite/getInformation?id=1234&detailLevel=2 and http://mysite/getEmployeeInfo?employeeId=4567&company=acmeinc.

For the clients accessing our service we want to provide special libraries that encapsulate the bevahiour. E.g. there will a client java-lib which translates a client-call getEmployeeInfo(..) either to

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

or to

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

and then return the result.

So for clients it will be completely transparent how the backend works if they use the library which handles the "translation".

What do you think are the pros and cons of each idea? I like my approach better because it looks "cleaner". But that is just a feeling which is difficult to argue about. Perhaps you can give me (or him) some thoughts about the design and also touch areas (scalability, security,...) or provide useful links about this matter

I'd probably vote for the JSON solution, even if they are more or less equivalent. (Both easily extendable, standard, future-proof solutions.)

The reasons for choosing JSON:

• There are a plethora of different libraries for different platforms that help you build correct objects, check that the string data is valid, etc.

• Unmarshalling of JSON data into objects. Some libraries (for example Gson) can automatically marshal and unmarshal JSON into objects. Saves you from writing your own code, and you get the benefit of using code that has been tested by others.

• Support for new interfaces. Suppose that you change your transport method to sockets, ftp(!) or whatever. You could still send the JSON objects to you backend using another transport.

I realize this question is old, but I think the answers here would guide developers down the wrong path.

In my experience you should always lean towards the more specific methods. Generic methods are difficult to test, difficult to wrap your head around and provide no (or minimal) IDE/compiler support. Such an api you are describing does not tell the user anything about what it will do.

Your own suggested api design is much better.

That being said, its a balancing act.

The JSON solution could be better because you can send complex object easier

But here it's just a little syntax detail, let the boss choose (or do a vote) and build your software.