Initializing a Simulation

Imports
HTTP API Simulation
Lifecycle Management

Imports

Add these imports when using the Embedded API Simulator. You may not need all of them depending on whether you use the predefined constants for various HTTP elements like methods (verbs), statuses, and header names.

import static com.apisimulator.embedded.SuchThat.*;
import static com.apisimulator.embedded.http.HttpApiSimulation.*;
import static com.apisimulator.http.Http1Header.*;
import static com.apisimulator.http.HttpMethod.*;
import static com.apisimulator.http.HttpStatus.*;

import com.apisimulator.embedded.http.HttpApiSimulation;

We decided not to pack everything in a way that all to import is a single class. We value code maintainability and think that having 2-3 more import statements, as needed, is better for supportability.

HTTP API Simulation

To simulate an HTTP API we first get HTTP API Simulation object that starts an API Simulator instance listening on a local port.

You may have guessed from the import statements above that an embedded HTTP API Simulation object is of type com.apisimulator.embedded.http.HttpApiSimulation. The simplest way to get an HTTP API Simulation object for a simulation named "my-awesome-simulation" is as follows:

httpApiSimulation("my-awesome-simulation");

That is equivalent to this:

httpApiSimulation("my-awesome-simulation", usingApiSimulator().instance());

Both create HTTP API Simulation object, which uses an API Simulator instance that is listening on the default port 6090.

We can define different port number. For example:

httpApiSimulation("my-awesome-simulation", usingApiSimulator().onPort(8080).instance());

Some hosts may have multiple network interfaces. This is how we can configure API Simulator to bind to a particular local IP:

httpApiSimulation("my-awesome-simulation",
   usingApiSimulator().onPort(8888).onHost("172.30.0.12").instance()
);

There is no limitation on using only one API Simulation instance at any given time. Just configure their API Simulators to listen on different port numbers.

Lifecycle Management

Below we take a quick look at the options to define, initialize, and shut down an HTTP API Simulation.

JUnit Class Rule

Using the JUnit’s @ClassRule annotation is a convenient way to have the simulation initialized and started before the execution of any test method in a test class and stopped after the last method’s execution completes. Here is how to use it:

@ClassRule
public static final JUnitHttpApiSimulation clApiSimulation =
   JUnitHttpApiSimulation.as(httpApiSimulation("payment-tests-api-simulation"));

Notice that per the @ClassRule annotation requirements, the field must be public and static.

JUnit Rule

Using the JUnit’s @Rule annotation causes the simulation to be re-initialized and started before the execution of each test method and automatically shut down after the method completes:

@Rule
public final JUnitHttpApiSimulation mApiSimulation =
   JUnitHttpApiSimulation.as(httpApiSimulation("junit-rule-simulation"));

Notice that per the @Rule annotation requirements, the field must be public and not static.

JUnit Member Instance

Using @Rule annotation may not be an option in some cases. To accomplish the same functionality, explicitly create the simulation in method annotated with @Before or named setUp(), and stop the simulation in method annotated with @After or named tearDown():

private HttpApiSimulation mApiSimulation = null;

@Before
public void setUp()
{
   mApiSimulation = httpApiSimulation("reinitialized-simulation");
}

@After
public void tearDown()
{
   if (mApiSimulation != null)
   {
      mApiSimulation.stop();
   }
}

Method Instance

Use method-scoped HTTP API Simulation instance to simulate remote APIs called within a method but not needed outside of it. Employing try..finally assures the simulation’s API Simulator is shutdown at the end and the port it was listening on is freed up even in case of an exception.

public void myMethod()
{
   ...

   HttpApiSimulation apiSim = null;
   try
   {
      apiSim = httpApiSimulation("method-scoped-simulation");

      apiSim.add(simlet("simlet-1")
         .when(...)
         .then(...)
      );

      apiSim.add(simlet("simlet-2")
         .when(...)
         .then(...)
      );

      ...
   }
   finally
   {
      if (apiSim != null)
      {
         apiSim.stop();
      }
   }
}

Static Instance

Defining an HTTP API Simulation instance as static in a class (and not annotated with @ClassRule) will start its API Simulator when the class is initialized. Shutting down the JVM will shut down the API Simulator and free up the port it was listening on.

public static final HttpApiSimulation clApiSimulation = httpApiSimulation("global-simulation");

We would love to hear your feedback! Shoot us an email to [feedback at APISimulator.com] about anything that is on your mind.

Happy API Simulating!