Creating an API in Java for the first time

Question

I have been given the task to design a list of APIs to be used by a GUI that I have to develop, in order to communicate with an external 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

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.

Answer 2

"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.