Fog Creek Software
Discussion Board




Maintaining Exported API's

The next version of our product is going to be exposing a number of API's.  This will meet the #1 request of our existing customers (ability to roll their own custom solutions using our product as the platform).  What has me concerned is ongoing support of those API's.  We understand the need to keep them stable at almost any cost (that is until we release the next major version), but I'd like to have more than our self-restraint and paranoid caution in place to prevent accidental modification of the API's.

I'd like to hear people's approaches to this "problem".  I can imagine us creating our own Ant task that knows what the API should be (i.e. it would have interfaces from the major release built into it, that it could use through reflection to ensure that the interfaces being built are consistent), but I'm hoping that there are more straightforward code stewardship-level actions that we can take to protect the APIs.

If you hadn't guessed already, we're using Java.

monadologist
Friday, July 25, 2003

For verifying Java APIs, you can't be Artima SuiteRunner.  http://www.artima.com/suiterunner/index.html

Matt
Friday, July 25, 2003

Expose your API's through interfaces only - don't expose classes directly. Lock down the files that contain these interfaces so that you can't change them accidentally.

Your internal implementation implements your API interfaces. Since the compiler will tell you if you forget to implement a method or change an interface function, you should be part of the way there.

The rest of the problem - what if you accidentally change the semantics - is best solved with unit tests.

Chris Tavares
Friday, July 25, 2003

And by all means... design them right the first time.  Otherwise you'll have to live with your mistakes and your customers' confusion for years to come.

anon
Sunday, July 27, 2003

*  Recent Topics

*  Fog Creek Home