Creating an API in Java for the first time

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!!!

From stackoverflow Tony

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

  Adriaan Koster : I don't think I agree about doing the minimum, unless you want to become a robot working in a factory. My advice is to start off by trying to understand the use cases and functional requirements if any are laid down already. Next think about these, and try to find any possible mistakes or missing requirements, and ask the relevant stakeholders about it. Then look at the existing class diagram and apply the same process of evaluation. It might also be a good idea to check out the phasing of the project: what are you required to build right now, and what is coming up in the following milestones?

  S.Lott : @Adriaan Koster: If you have some experience writing API's, that's a good approach. For your first-ever API, that's a recipe for over-engineering and creating something horribly complex. Generally, the initial set of methods and attributes include some awkward features. Fixing those is enough to get started.
  From S.Lott

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

  From jqno

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

  From Adrian

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

  meriton : +1 for great link
  From delfuego