PhET-iO API Overview

The PhET-iO API is how our Partners communicate with PhET Simulations to achieve interoperability. Each PhET Simulation is built from a shared library of code, and a Model-View-Controller architecture pattern is used in development, resulting in consistency of architecture across Simulations. However, each PhET Simulation is designed independently to serve specific Pedagogical needs, therefore the exact functionality available via the PhET-iO API from one Simulation to another, will vary.

Overall, the complete set of endpoints available in the PhET-iO API is classified according to whether it belongs to the overall PhET-iO Feature Set or if it stems from Simulation-specific functionality. The following diagram illustrates this distinction, at a high level. More detailed information can be found in the PhET-iO Developer's Guide.

The PhET-iO Feature Set is defined by how you can interact across multiple Simulations in a consistent manner. For example, the current PhET-iO Feature Set, called Hydrogen, contains features like the ability to launch a simulation, set the display size, listen for an event, take a screenshot, load a previously saved state and then get or set those states based on the user’s interaction with the Simulation. Those endpoints behave in the same manner from one Simulation to another. Whereas, individual PhET-iO Elements stemming from a Simulation, will vary from Simulation to Simulation (like the temperature of a cloud, or position of a circuit).

The PhET-iO Team prioritizes stability for our Partners. Our API will only change in defined ways in the future or it will not change at all. Hence, PhET-iO API Stability means that the wrappers our Partners create will remain functional for a period of at least 5 years and upgrading to a new version of the Simulation will not be required.

A wrapper is an HTML file written in Javascript, which provides the actual code to execute your customizations and integrations. If the customizations are created and downloaded via PhET-iO Studio, then those wrappers are considered Standard PhET-iO Wrappers. Whereas, wrappers that begin with our wrapper template and are then modified are considered Custom PhET-iO Wrappers.

The details relating to PhET-iO API stability, are as follows:

• Partners are not required to upgrade when a new version of a Simulation (major.minor) becomes available. All versions of the simulation will be supported through maintenance releases for a period of at least 5 years.
• The addition of new PhET-iO API Feature Set elements or methods will not break or change the meaning of existing elements or methods.
• In general, PhET does not release new versions of a Simulation on a frequent basis due to their overarching complexity and the care taken in the initial pedagogy design and software development.
• If a Partner chooses to upgrade to the next minor version of a Simulation and uses the Standard PhET-iO Wrapper for their customizations, their upgrade is supported via PhET-iO Studio. Partners may load their Standard PhET-iO Wrapper into the current Studio and their customizations will be preserved to the extent possible. Any unsupported customizations will be documented. We call this process PhET-iO Migration.