Question

I am writing an API for my application and have a few open questions (with versioning in mind).

• Should users call directly my objects or need I provide some abstraction?
• Should code that users wrote with version X of the API only work with version X or should it work also with the latest version?

Initially I thought “abstraction” and “latest”. But .Net (or Silverlight) for example exposes concrete classes, ships with all previous versions, and also a 2.0 dll will run with 2.0 CLR even if 4.0 is installed.

I am looking for examples of API strategy of known .Net projects (client apps). For example NUnit and NHibernate but any other library you know of is great.

Answer 1

I think both answers depend on your necessities and must importantly: business constraints.

• Abstraction or not? That depends on whether it makes sense for the consumer to work with the objects themselves or, more importantly, if the users are ALLOWED to do so. If users can use them (in a business logic way) then expose the classes.

Also remember that you do not have to externalize all of the object’s functionality, you can keep attributes for the internal use of the class or even for the DLL using the “friend” modifier: http://msdn.microsoft.com/en-us/library/08w05ey2.aspx

Ex. You are designing an API for a bank and you want to let your consumers work with the “Client” class but you sure don’t want them calling Client.GetTotalBalance().

Taking that into account is perfectly safe for you to externalize the objects, if you keep what’s private, private; .NET is really strong there.

• Forward Compatibility? You should always try and design your APIs in a way that allows for expansion, be sure to use strong naming convention so that you can keep the method’s names for as long as you need them, in that order you will guarantee that old code runs with newer versions even if it doesn’t consume all the new resources available.

That doesn’t mean, though, that you cannot take methods away if you need to, specially if security risks are involved.

Hope that helps :).

2 more things: As “Reed Copsey” suggested, take a look at: http://msdn.microsoft.com/en-us/library/ms229042.aspx.

And I’d like to suggest, if you are starting from scratch and have the time to, that you implement serialization for your classes, it may come in really handy depending on the use for your API: http://msdn.microsoft.com/en-us/library/7ay27kt9(VS.80).aspx