Language Agnostic API

Question

I am planning on putting up a web service, or some other service exposed over the internet. I would like to create an API for applications to interact with this service. I would like the API to be usable in different languages, such as Java, C++, C#, or PHP. How can I maintain one code base for my API, but distribute nice packaged binaries for all these languages? Also, I may want to consider this could be cross platform as well.

Update 1

I'm early days on Web Services, but I think one of the key points is that lots of tooling supports the implementation of clients based on the description of the service like WDSL. I've not delivered any client-side software with anything I've done, I expect any user to be able to build their own clients suited to their needs. --Brabster's Answer

I am not opposed to making it a straight web service then giving out a WSDL file. But what if I want the client API to do some logic, encryption, error checking or so on?

Update 2

As far as expecting the client that is using your API to do anything, you can't! There is nothing you will be able to do to ensure that the consumer of the API will do anything right. That's why robust error handling is so important. You must check and double check any and everything that comes from the client. You must always be suspicious of it, and even assume that it is malicious. There really is no good way around that fact. --Ryan Guill's Answer

My original idea was to create a DLL or Assembly in .NET, then the client is making calls into this code that is running client side. This code may talk via any communications protocol back to the server, but my API would be running on their box. I guess REST does not really accomplish this. It seems like in REST everything is still an HTTP post. It is almost web services with out soap.

Update 3

I have accepted Ryan Guill's answer. I think the general idea is that I need to expose a network service of some sort, with the lowest barrier to the client. That way anyone can connect. Then just have all my code run on the server. That seems to be accepted as the only want to really achieve the platform and language independence I am after.

Thanks for all the input.

Answer 1

I'm early days on Web Services, but I think one of the key points is that lots of tooling supports the implementation of clients based on the description of the service like WDSL.

I've not delivered any client-side software with anything I've done, I expect any user to be able to build their own clients suited to their needs.

If you check out the flickr API as suggested by one of your other answers, I don't think they supply client side code, other people have built and contributed client side stuff.

Answer 2

I would use a REST API, similar to the way Flickr's API works: http://flickr.com/services/api/

It is fairly simple to create and maintain, the biggest downsides is that it takes a lot of documentation (but pretty much any way you do an API will have this issue) and that robust error handling is a must.

But in my opinion, its the best way to create an API that is the closes to cross platform/cross language as possible.

More information here: http://www.xfront.com/REST-Web-Services.html

Update: The submitter added the following to the post:

I am not opposed to making it a straight web service then giving out a WSDL file. But what if I want the client API to do some logic, encryption, error checking or so on?

I personally do not like using SOAP (using a WSDL). There is a lot of inherent overhead to using SOAP, both on the server and the client. I think that is why you see more and more public API's being written using REST. It really lowers the barrier to entry to the lowest common denominator, allowing anything that can use basic HTTP (GET and POST (also PUT and DELETE for the "proper" way of doing it)) to use the API.

Some more examples of public API's written using REST: twitter, vimeo, Google

As far as expecting the client that is using your API to do anything, you can't! There is nothing you will be able to do to ensure that the consumer of the API will do anything right. That's why robust error handling is so important. You must check and double check any and everything that comes from the client. You must always be suspicious of it, and even assume that it is malicious. There really is no good way around that fact.

Update 2: the submitter added the following to the post:

My original idea was to create a DLL or Assembly in .NET, then the client is making calls into this code that is running client side. This code may talk via any communications protocol back to the server, but my API would be running on their box. I guess REST does not really accomplish this. It seems like in REST everything is still an HTTP post. It is almost web services with out soap.

You can certainly do this, but that is only going to work for .NET languages, meaning that your cross-platform and cross-language benefits are out the window. And still, in the end, are you really preventing anything? The developer is going to either use your remote API, or your local DLL or Assembly. Either way, he is going to have to know how to use it and use it right, otherwise you are going to throw an error. All you are really doing is changing where the errors get thrown from. Which may be important to you (if so, mention why) but really isn't changing anything in the equation.

But you are somewhat correct in saying REST is kind of like web-services without the SOAP. Technically REST is web-services too, its just that web-services have come to generally mean SOAP. It really is a different way of achieving the same thing. The biggest differences are though that it takes more programming and thought on your side (and potentially more programming on the client side) but you trade that for robustness, less overhead in both the consumer and the server, and the widest possible audience for the API. It really is the lowest common denominator.

Answer 3

Simple answer, no.

Complex answer: create an API and compile it to a COM dll. Then, just build the wrapper code for the languages that can't handle that.

Simple answer #2, make the original service so trivial, or so universally acceptable, as to not require an API (I usually implemented this through server-side database polling. Ugly but any language that can access a database can utilize the program).