Epicenter APIs: Version History
From time to time, Epicenter APIs undergo major version changes. When this happens, the version changes are always called out in the Release Notes, and the previous version will remain available for some time before being deprecated.
Current Version
The current version of the Epicenter RESTful APIs is v2.
Forio recommends using v2 for all new projects.
Forio also recommends converting existing projects to use v2, with one exception:
- If your project relies on accessing runs that have already been created with v1, the entire project should continue to use v1 for now. This is not common, but might occur for example if you have a leaderboard showing scores for everyone that has ever played. See the Major Differences between v1 and v2 section, below.
To access the v2 APIs, you can:
- Use Epicenter.js 2.0 or later.
- Preface all of your Epicenter API calls with
/v2/, for example,POST /v2/run/acme/supply-chain-game.
Important: Although the current version of the Epicenter RESTful APIs is v2, the default version is still v1. This means that you'll be accessing the v1 APIs if you:
- Use Epicenter.js 1.8.1 or earlier
- Preface all of your Epicenter API calls with
/v1/or/. For example,POST /v1/run/acme/supply-chain-gameandPOST /run/acme/supply-chain-gameboth use the v1 APIs.
In the future, the default version will change to v2.
Why Use v2?
The change from v1 to v2 APIs is largely transparent -- there are no known breaking changes. That said, if you are considering moving an existing project from v1 to v2, you'll want to look at the Major Differences between v1 and v2 section, below, and thoroughly test your project.
Under the hood, runs are now created on a new and improved distributed model service infrastructure, which provides increased stability and improved logging and error reporting. Performance, especially during run creation, is also improved.
Major Differences between v1 and v2
Your project must use only one version of the APIs -- either v1 or v2. Don't mix them. In particular, runs created with v1 cannot be retrieved with v2, and vice versa. (If you try, you'll get a 404 error.) If your project has been in production for some time, and requires the display of previous runs, you should wait until a future Epicenter release provides for seamless migration of run data before converting your project to the v2 APIs.
Error messages are more detailed and more specific, especially for errors within the model (e.g. errors encountered when creating runs or calling operations).
Run Ids have a slightly different format: In v1 they contain hyphens (e.g. "8094ba75-62c6-4631-9c31-41cba6a3b3f8"), but in v2 they do not (e.g. "000001576501ce3b3387aa984aa94676a5a6"). Although not otherwise a remarkable difference, this is an easy way to confirm which API version you are using.
There are a few minor language differences. See the Writing your Model pages for details. In particular,
- Julia models no longer require modules, but if you have modules, then variable names must include the module name in your
GETrequests. - Julia models also no longer require variables to be part of a complex type if you want to update them without using an operation.
- Some of the function names in the
Epicenter.Rpackage, used with some R models, have changed. If you use this package, make sure you review its use.
- Julia models no longer require modules, but if you have modules, then variable names must include the module name in your
Optionally, there is a new model context format. Context files are optional for all models, and can include additional information about the context in which your model should be run. If you have written a .cfg file for your project to specify this context, you now have two choices: you can keep your .cfg file as-is, or you can convert it to a .ctx file, which has a slightly different format. See the Model Context page for specifics.
Previous Versions
The previous major version of the Epicenter RESTful APIs is v1.
To access the v1 APIs, you can:
- Use Epicenter.js 1.8.1 or earlier.
- Preface all of your Epicenter API calls with
/v1/.
You can view archived versions of the Epicenter v1 API documentation here: