Editing Modding (section)

== Calling the API from a frontend mod ==

<code>js/api.js</code> is the '''wrapper layer''' for the REST API: each endpoint has a named async function with semantic parameters, plus the live <code>gameStore</code>, plus exported '''ID constants''' (entity IDs, industry indices, special asset IDs, <code>UI_*</code> report IDs). '''Frontend mods should call <code>api.js</code> functions, not raw HTTP.'''

<pre>
import * as api from '../api.js';

await api.buyStock(companyId);                    // /buy_stock
await api.setDividend(actingAsId);                // /set_dividend
await api.merger(targetId, actingAsId);           // /merger
await api.cheatAddCash();                         // /cheat_add_cash
const state = await api.getGameState();           // GET /gamestate
</pre>

For endpoints that don't have a named wrapper yet, four request shapes are also exported:

{| class="wikitable"
! Helper !! Body shape !! Use
|-
| <code>postNoArg(path)</code> || <code>{}</code> || actions with no parameter
|-
| <code>postIdArg(path, id)</code> || <code>{ id }</code> || actions on a specific entity / slot
|-
| <code>postIdArgWithActingAs(path, id, actingAsId)</code> || <code>{ id, intParam2 }</code> || most corporate / trade actions
|-
| <code>postOptionsTradeWithActingAs(path, id, actingAsId, underlyingId)</code> || <code>{ id, intParam2, underlyingId }</code> || options trades
|-
| <code>postStringArg(path, str)</code> || <code>{ str }</code> || actions taking a string (e.g. save-as filename)
|-
| <code>getJSON(path)</code> || - || GET endpoints
|}

For wire-level details (the underlying routes, the JSON body the bridge actually receives, what each generic field means per endpoint), see [[#REST API reference|§REST API reference]].