Simulation API Exercise

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
• Leads to readable code
• Hard to misuse
• Provides for extension

This exercise asks you to start the process of changing your thinking from simply programming to API design.

To work on today's exercise, create a file, called doc/API_DISCUSSION.md, using Gitlab's markdown format, within your Simulation team's repository to capture the results of your team's discussion.

API Discovery

Typically there are two kinds of programmers that are interested in your code:

• External:
  • typical goal: how to provide useful access to information that encapsulates the implementation details while allowing for extensions for as wide a variety of unexpected features as possible
  • such as: between the frontend and backend (e.g., between sub-groups within the project)
  • such as: between the platform and developers for the platform (e.g., between iOS and app developers or between Facebook and add-ons or game developers)
  • note: all of these methods will need to be public
• Internal:
  • typical goal: how to provide paths for extension through implementing interfaces or subclasses for expected new features while keeping the core implementation closed to modification
  • such as: between the backend and its future maintenance programmers (e.g., between programmers within the same sub-group)
  • such as: between the platform and developers that port that platform to new technologies (e.g., between Facebook and its mobile and web teams)
  • note: while some of these methods may be public, many may be protected or package friendly

Examine the effective API, all the public methods, from your project and categorize each method from following perspectives (where each sub-module, Simulation, Configuration, and Visualization, within the overall project can be seen as a potential external client of the other's API):

• the method should be part of the external API because it helps people on the team working in other modules write their code
• the method should be part of the internal API because it helps people on the team within the module implement its abstractions
• the method should not be part of any API (i.e., it should not be public)

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

API Documentation

Most APIs are documented using a standard technique like Javadoc to automatically generate nice looking documentation (like Java's Collections or JavaFX). For this exercise, since you are just starting the process of thinking about APIs, we are not requiring this style of documentation but it will be required for later projects.

Now that you have classified the public methods in the project, describe how to use your discovered APIs (external and internal for the Simulation module) to do the following tasks:

• external: as a client of the backend, the frontend selects an existing simulation to display and then starts running that kind of simulation, updating its own grid visualization
• internal: a new developer joins the the backend team and adds a new possible kind of simulation that can be available for the frontend to choose (i.e., a hypothetical seventh kind of simulation)

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

• English: how do you want programmers to think of the process of using the API to accomplish this task using metaphors or analogies (e.g., folder paradigm), or standard programming ideas (e.g., step by step or substitution via polymorphism) beyond simply restating the procedural steps
• Java: list the actual Java methods you expect to use from the API to accomplish this task with a comment about how they would be used (e.g., call, implement, or change)

API Vision

Now that you have a sense of the kind of service your project currently provides to programmers, think about the kind of service you wish it provided. In other words, spend this time designing the 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 programmers. 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)?

Using the desirable characteristics of an API listed 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:

• external: as a client of the backend, the frontend selects an existing simulation to display and then starts running that kind of simulation, updating its own grid visualization
• internal: a new developer joins the the backend team and adds a new possible kind of simulation that can be available for the frontend to choose (i.e., a hypothetical seventh kind of simulation)

Again, writing both English and Java descriptions of the task as well as a justification for each as to why you think this version is better using your answers to the questions above in this section.

Note, feel free to make as extensive changes as you want because this is a thought exercise — you are not expected to implement this new vision this week.

Submission

At the end of class, use Gitlab's Merge Request to submit your group's doc/API_DISCUSSION.md file to your team's repository. Make sure everyone's NetIDs that worked on it are in the title of your Merge Request.