= The DETER System Programming Interface =

[[TOC]]

== Introduction ==

The DETER System Programming Interface (SPI) is a standard interface for manipulating fundamental DETER abstractions used to manage testbed resources and to marshall those resources into  network and cybersecurity experiments.  The SPI is analogous to an operating system's system call interface.  It provides the fundamental abstractions that enable application programmers to make tools that are useful to researchers.

There are two motivations for building the SPI: first that the SPI is a context and programming framework for new DETER abstractions that subsumes the existing Emulab codebase cleanly.  Second the SPI provides a context in which new developers can extend those abstractions to provide new functionality and to improve their scaling properties.

The SPI is fundamentally a tool-builder's interface.  Researchers performing experiments or students performing class exercises are unlikely to access SPI methods directly, though we expect that higher level tools and interfaces will make the fundamental abstractions visible.

=== The Fundamental Abstractions ===

There are 6 first class abstractions that make up the DETER SPI.  These are:

 Users::
  A researcher who builds and carries out experiments using resources controlled by the testbed.
 Projects::
  Administrative groupings of users that embody the trust chains that underly researcher access.  A researcher has access to the testbed as a whole because they are a member of an approved project.  Trusted users can add other users to an approved project, reducing the administrative overhead.
 Circles::
  Groupings of trusted users that embody the sharing of data and resources among researchers.  Adding or removing users from circles gives them permission to access resources in use for experimentation or excludes them from such resources.
 Experiments::
  A description of a research activity.  An experiment is composed of '''aspects''', each of which embodies some facet of the activity.  Currently the SPI recognizes 4 aspects:
   * '''Layout''': the arrangement and specification of an experiment's elements that make up the experimental apparatus
   * '''Procedure''': The steps taken to carry out an experiment
   * '''Data Management''': The resources and processes used to collect and process data generated by the experiment
   * '''Constraints''': Correctness requirements that must be met in a valid experiment.
  Additional aspects can be specified by users and accessed by running experiments.  We document a plug-in interface (below) that explains how new aspects can enter the system.
  Access to experiments and the resources attached to them is controlled by assigning rights to circles.
 Libraries::
  Collections of experiments grouped by function or semantics.  Libraries allow researchers to organize their experiments and share them with other researchers (by assigning rights to circles).
 Realizations::
  A realization is the binding of resources to an experiment.  Users can inspect and modify such bindings in carrying out their experiments.

We describe each of these in more detail below.

=== The Implementation Framework ===