This week's book giveaway is in the OCAJP 8 forum. We're giving away four copies of OCA Java SE 8 Programmer I Study Guide and have Edward Finegan & Robert Liguori on-line! See this thread for details.
I need to know what the actual definition (accepted descriptions?) of what an API actually needs to be and/or entails. I need to create access and controls into a legacy based system that has indirect access by java. If this is done right, this could become part of a commercial product, but I just need some advice / clarification on the subject so that I can proceed with MUCH caution.
Probably you are not looking for the definition of what an API is, but for suggestions on how to design a good API for your software. There's ofcourse a lot that can be said about that subject.
One of the hardest things when designing an API is that it needs to be future-proof: if you develop a new version of your software in the future, you probably don't want to change the API in such a way that it's incompatible with older versions. Your clients (people who are using the API) won't be happy if they have to modify their programs to work with your new version.
In the standard Java API, some methods are marked deprecated (with the @deprecated Javadoc tag or the @Deprecated annotation) to indicate that the method should not be used anymore because the API has changed. Note that Sun until now has deprecated a number of classes, interfaces and methods in the standard Java API, but they've never actually removed any of those deprecated things. If they'd do that, they'd break compatibility with software that was written with the older version of the API.
So you have to be very careful to design an API for your software, and you'll need to think especially about how future-proof your API is going to be.