Lab Exercise : API Design

An Application Programming Interface, API, is simply all the public classes and their public methods in your program. However, thinking about the public methods together as an interface to your program has the power to change how you perceive those methods from just something necessary to make the program functional to providing a service to other programmers (even those on your own team!). An API, then, essentially becomes a contract and developers, now clients, are enticed to use the API because they know they can rely on that contract (even if the underlying implementation changes). Thus, many see API design as the most critical part of designing a program, because it affects the design of other components dependent on them.

Although the concept is inherently subjective, most developers seem to agree on the main desirable characteristics of an API:

• Easy to learn
• Hard to misuse
• Provides for extension

This exercise helps you to start the process of changing your thinking from simply programming to API design by exploring existing APIs.

Collections

Start by considering an API you are likely very familiar with: Java's collection classes. That linked overview includes the design goals and links to the documentation as well.

Use the following questions to guide your discussion:

• How many interfaces, a way of creating "smaller" abstractions, do specific concrete collection classes implement (such as LinkedList)? What do you think is the purpose of each interface?
• How many levels of superclasses do specific concrete collection classes have (such as HashMap)? What do you think is the purpose of each inheritance level?
• How many different implementations are there for a specific collection class (such as Set)? Do you think the number justifies it being an interface or not?
• What methods are common to all collections? A specific collection (such as Queue)?
• What is the purpose of the utility classes Collections, Arrays, and Objects? Why not add that functionality directly to the collection types themselves?
• What is wrong with the design of the Stack class? Note, it is leftover from the original version of the Collections API (that used Vector instead of ArrayList)

If there is something you like or dislike about using Collections or something your learned about design during the discussion, make sure to back it up with a specific example. During your study, feel free to search the Internet for other resources beyond the Java documentation.

Cell Society

Examine the effective API (all the public methods) from one person's Cell Society project and categorize each method from following perspectives, where each part (Simulation, Configuration, or Visualization) is a potential external client of a class's API:

• the method should be in the API because it helps developers working on other parts write their code
• the method should be in an internal API because it helps developers within the part implement its abstractions (but perhaps still needs to be public)
• the method should not in any API (i.e., it should not be public)

A simplified view of just the public methods for each team is available here.

Apply to Examples

Now that you have classified the public methods, describe how to use the discovered APIs for the Simulation part to do the following tasks:

• the frontend selects an existing simulation to display and then starts running that kind of simulation, updating its own grid visualization
• the backend adds a new possible kind of simulation that can be available for the frontend to choose (i.e., a simulation whose states and rules do not currently exist)

Your written explanation should include both English and Java descriptions of each task:

• English: what are your design goals and how do you want developers to think about accomplish a task with your API using metaphors or analogies (e.g., folder or state machine paradigm)
• Java: what standard programming ideas (e.g., step by step or substitution via polymorphism) are going to be used and what actual Java classes and methods make up the API to accomplish a task

Create a Vision

Now that you have a sense of the kind of service your project currently provides to developers, think about the kind of service you wish it provided. In other words, spend this time designing an API instead of just having it happen. Think about what classes and methods you can provide that, in addition to upholding the APIE principles of Object-Oriented Design, create a more useful and flexible experience for other developers. For example, does adding something new require adding new method(s) to class(es) (not closed or easy to discover) or adding a new subclass (more conventional and flexible)?

Create a new set of classes and their public methods for a basic Simulation API. You can certainly reuse existing classes and methods, but keep in mind that you are trying to create a more open, service, experience for developers to create and use new Simulations.

Using the desirable characteristics of an API given above, think about the following questions as you design:

• How can you reduce the number of methods needed to do a task or make them easier to find and understand?
• What can you take as a parameter or return that helps other programmers write their own well designed code?
• How can you simplify the expectations for each method so they are easier use (and thus harder to misuse)?
• What can you take as a parameter or return that makes fewer assumptions about the implementation or this specific example?

Solve the same tasks from the previous section with your new API, writing both English and Java descriptions of each task:

• the frontend selects an existing simulation to display and then starts running that kind of simulation, updating its own grid visualization
• the backend adds a new possible kind of simulation that can be available for the frontend to choose (i.e., a simulation whose states and rules do not currently exist)

Hopefully, your new API will feel easier to use and extend, as well as harder to misuse. If not, try again - revise and iterate your API until you feel good about the service it provides.