API across multiple languages. Use idiomatic code for each or support the same API structure

Question

I'm currently working on a project which requires to support multiple languages as first class citizens and I'm facing a dilemma. I can choose between implementing the API as closely as possible for each language. But this invariable leads me to abandon some best practice for the language. E.g. C# events instead of a list of callbacks.

So what I am wondering is what you would prefer as a user or a developer of such an API. Keep the API as closely as possible between languages. Or diverge when a language has "better" way to do something?

Answer 1

Conform to the language and not to the project API.

The reason is simple. No matter how important a service is, how much mindshare it occupies in your consciousness or that of its maintainers... it can't possibly rival the mindshare that an application programmer reserves for their favorite programming language. Talking to service XYZ will always be just one connection among many that they have to make, and always requires a bit of task-specific look-up of details.

Therefore, there is little point in making talking to XYZ via language A easier for someone who has already talked to it in language B, and anyway this will rarely happen. But there is a lot of advantage in making connecting to XYZ in language A easy for language A users, because there will be quite a few of those.

Answer 2

Find a compromise.

On one hand, you want to make all of your API users happy, and thus design the API implementation for each programming language as idiomatic as you can. On the other hand, you have only limited resources. If you will be able, for example, to generate an API implementation for several languages from a common source, instead of writing and optimizing it manually, you might be able to reduce maintenance efforts by an order of magnitude. That, however, will probably lead to less idiomatic code.

You should also consider

• how many API users you really expect for each language

• how important it is for you to satisfy each and everyone

Note also, if you targeting for .NET (since you mentioned C#), an API implementation in this language will automatically be reusable by any other .NET language, so avoid to revinvent the wheel.