API strategy of known .Net projects

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

Personally, I don't see much reason to put extra abstraction in place, at least not in .NET. In .NET, it's often better and easier to use abstract classes instead of interfaces, potentially with factory methods. This can let users work with (what appears to be) your objects directly, but still provides you a clean versioning support.

As for future proofing your API - if you follow the Design Guidelines for Designing Class Libraries, you're much more likely to naturally create an API that will be forward compatible. Many of the design guidelines (such as preferring abstract classes, using unsealed classes, etc) naturally lead to designing for extensibility, which includes your own extensibility in future versions.

Unless there is a strong reason to avoid this, I prefer to opt towards allowing for future proofing an API - it tends to be a (little) more work up front, but lowers the maintenance cost later, especially since it helps avoid deployment issues from versioning, etc.

Most .NET projects, including the ones you listed, tend to take this approach. Usually, breaking API is only done on a "major" version, and even then, it's kept to a minimum. If you lock your users into your current API on every release, you're providing motivation for them to NOT upgrade to your latest version - this is the opposite of the intended motivation, as this increases your support requirements (you have to support more, older versions), and keeps users from using your latest and greatest features.

Answer 2

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