Appendix B: APIs

From OSPDocs

APIs Needed

Writing these APIs is work in process.

To take full advantage of the enormous amount of great open source material out there, we want to be able to talk to other people’s programs. So we will need to define a standard way of communicating with our simulation engine, to facilitate the creation of wrappers that we can then use around other people’s code (OPC.)

Communicating with Simulation Sections

Info from Engine to a View

Information sent every time to every page (view) shown in the simulation as part of an HTTP request:

SIM_ID=1&SIM_SESSION_ID&SIM_ACTOR_ID=1&SIM_ROUND_ID

Where the following represent:

SIM_ID Unique identifier of this simulation.

SIM_SESSION_ID Unique identifier of this particular simulation being run.

SIM_ACTOR_ID Unique identifier of this actor in the simulation.

SIM_ROUND_ID The number of this simulation round.

Information from a view (due to user action) back to the Engine

Any application will pass back to the simulation engine this information:

<USIP_OSCW_DATA_PACKET>

<SIM_ID>[1....n]</SIM_ID>

<SIM_SESSION_ID>[1....n]</SIM_SESSION_ID>

<SIM_ACTOR_ID>[1....n]</SIM_ACTOR_ID>

<SIM_ROUND_ID>[1....n]</SIM_ROUND_ID>

<SIM_VAR_LOCAL_MSG_ID>[1....n]</SIM_VAR_LOCAL_MSG_ID>

<SIM_VAR_NAME>[character_string]</SIM_VAR_NAME>

<SIM_VAR_NEW_VALUE>[any]</SIM_VAR_NEW_VALUE>

</USIP_OSCW_DATA_PACKET>

Response sent back to above packet

The simulation engine will pass back the following:

<USIP_OSCW_RESPONSE_PACKET>

<SIM_VAR_LOCAL_MSG_ID>[1....n]</SIM_VAR_LOCAL_MSG_ID>

<SIM_RESPONSE>[accepted|rejected]</SIM_RESPONSE>

<SIM_RESPONSE_ERR_CODE>[1....n]</SIM_RESPONSE_ERR_CODE>

<SIM_RESPONSE_REASON>[optional explanation]</SIM_RESPONSE_REASON>

</USIP_OSCW_RESPONSE_PACKET>