Creating an API in Java for the first time

Question

I am a novice in Java. I have been given the task to design a list of APIs to be used by a GUI to communicate with an application. Considering that the application has just been designed and I have its initial class diagram, should I:

1- Just list the fields and methods from this application class diagram that will be needed by the GUI to communicate with the application

or

2- Create a list of completely new fields and methods needed by the GUI to communicate with the application which the application developer should create

Thanks in advance!!!

Answer 1

"Just list the fields and methods from this application class diagram that will be needed by the GUI to communicate with the application"

This works really well.

After doing this, try to write documentation -- with detailed examples. If your documentation is hard to write, confusing or lame, then you need to fix the API's to add features.

Then show it to other people.

If people are confused or complain, then you may need to add additional features to the API.

Until people are actually confused or actually complain, don't do anything more than the minimum.

Answer 2

I'd make the API (semi-)independent from the implementation of the GUI, because later you might want to create a different interface to the same application, or simply change the GUI, and then you're stuck with whatever you created for the first pass of your first GUI.

Also, I highly recommend taking a look at Josh Bloch's talk about API design. Bloch is the guy who designed the Java Collections API.

Answer 3

I would specify an interface. This decouples GUI and applications.

The GUI will only use the interface (except for one call to a factory method that return a concrete object) and the API will implement the interface. Like that none of the class names of the application is known to the GUI. This leads to a stable design that is the most fit for future evolution.

Also, the interface serves as a nice documentation of the complete API.

Answer 4

One of the best guides to API design I've read is The Little Manual of API Design (PDF), which has some great, platform-neutral guidance as to how to create an API for an application or service. Some of the most important guidance it gives is:

• create use cases before you start coding the API itself;
• get peer review of the API design before you code it;
• write examples against the API to test its robustness.

The first tip is the best, IMHO; it prevents you from coding an API that provides the world when all your use cases require is a small portion of that world. It also forces you to think out how it'll be used, and make design decisions based on those uses rather than in the abstract.