Lab Team Meeting: Creating an API

In this lab, you will practice designing APIs, the public classes and their public methods. Thinking about public methods as a service has the power to change your purpose: from simply programming to finish functionality to providing a means to help other programmers innovate (even those on your own team!). An API then, is essentially a contract with developers, now clients, who are enticed to use the API because they know they can rely on the stability of 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 dependent components.

In your Cell Society teams, complete the following steps:

1. Practice thinking critically about API design
2. Review Design Principles
3. Practice designing APIs
4. Shared API design

The result of this lab will be a set of documents that captures the important points of your team's several directed discussions.

Practice Thinking Critically about API Design

Complete this exercise to examine Java's Collections API from a design perspective (instead of as a user) to compare your experiences with its documented goals and motivations.

Before Moving On: Add your names and summary of your discussion to the file doc/COLLECTION_API.md, then add, commit the file, and push it to your project repository.

Review Design Principles

Discuss your understanding of Design Principles by having each person share their interpretation of these Design Principles related to abstractions:

• Open-Closed Principle
• Liskov Substitution Principle

Provide a brief summary of this discussion in the file REFACTORING_DISCUSSION.md.

Then, choose three abstractions (inheritance hierarchies or interfaces) from your project and discuss:

1. Which, if any, of those principles the abstraction embodies (i.e., how it helps close a core algorithm in your project or how its subclasses are designed to be substitutable)
2. How the abstraction could better embody those principles

Finally, brainstorm three new abstractions that would be helpful to create in light of the given change requirements.

You will know your design is on the right track if the resulting code will:

• refer to abstractions more than concrete classes directly (especially abstractions your team created)
• rely on polymorphism when calling methods rather than conditional logic based on a concrete class's "type"
• use subclasses to make it clear and easy to determine where to write feature variations

Before Moving On: add your names, shared Design Principle understanding, three current abstractions, and three new abstractions to the doc/REFACTORING_DISCUSSION.md file, then add, commit the file, and push it to your project repository.

Practice Designing APIs

Even though APIs are simply the public classes and their public methods, your mindset is vital to clarify your design intentions about how you want them used and extended in response to changes.

When designing a set of services to be used by other developers (current and future team members), consider the following:

• Goal: how to encapsulate the implementation details while encouraging changes (extensions for as many different kinds of features as possible)
  • Such as: between the backend and frontend (e.g., between programmers in a project's other sub-groups to allow them to develop independently and in parallel)
  • Such as: between a platform and completely external developers (e.g., between iOS and app developers or between Unity and game developers)
• Contract: what services can you provide to encourage other programmers to build their own new functionality?
  • How do you plan to encapsulate them from implementation changes?
  • What objects will be used for communication, making clear:
    • how needed information will be delivered to where it is needed
    • what will be abstractions
    • what errors may be thrown
    • what things will be immutable
    • how to make the process as active as possible (not just giving out raw data)

Examine the classes related to Simulations in your Model package from the perspective of APIs by categorizing each public method as:

• should not be part of the Simulation API (i.e., it should be made private)
• should be part of the API, but should be generalized or changed to better support new changes
• should be made internal (protected) because it primarily serves maintaining adding new Simulations
• should declare likely Exceptions that might occur
• should be made immutable to remove the possibility that it could be used to corrupt the Model's internal state

A simplified view of only the public/protected methods for each team is available here.

Now that you have a sense of the kind of service your project actually 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. Write a simplified (i.e., less than "one page" each) description and goals for the Simulation Model API. Note which classes are abstract/interface and which are concrete (and justify why an abstraction is not appropriate).

Then describe how to use your new Simulation Model API to do the following tasks:

• as a client, the Configuration confirms an existing simulation and then initializes its starting values
• as a client, the View selects an existing simulation to display, starts running that kind of simulation, and then updates its visualization

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., event-response 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)
  Note, include any Exceptions you plan to throw because of errors that might occur within your methods.

Before Moving On: Add the following to the file doc/SIMULATION_API.md, and add, commit the file, and push it to your project repository:

• your categorized methods
• your "one-page" API design
• English and Java descriptions for the API tasks

Shared API Design

Pair up with another team, compare your APIs, and attempt to come up with a common API that could work for both of your projects.

This should require each team to justify their Design Contract, explore trade-offs between the two APIs, and then compromise on choosing one API to promote (a complete existing one or, more likely, a compromise between the two versions). Note, it is very reasonable that much discussion will focus primarily on class and method names! 

Before Moving On: Add your names and summary of your discussion to the file doc/SHARED_API.md, then add, commit the file, and push it to each team's project repository.

Submitting your Work

At the end of lab, push your team's Markdown files to the doc folder of your team repository to submit your notes about your teams' discussions.

• COLLECTION_API.md
• REFACTORING_DISCUSSION.md
• SIMULATION_API.md
• SHARED_API.md

Make sure the text of your final commit message is of the form "lab_api_design - NetIDs".