Oms web service

From OpenM++
Jump to: navigation, search

Contents

What is openM++ web-service

OpenM++ web-service (oms) is a JSON web-service written in Go and used from openM++ UI JavaScript. Today most of popular development platforms (.NET, Java, Python, Perl, R, JavaScript, etc.) with only few lines of code allow to create HTTP client and send-receive JSON data. That makes integration with openM++ very easy.

How to start openM++ web-service

OpenM++ web-service does not required any installation. It can be run with default settings from command-line prompt.

To start openM++ web-service on Windows:

  • download and unzip openM++ binaries into C:\SomeDir\
  • run oms from command-line:
C:
cd \SomeDir\openmpp_win_20180205\
bin\oms.exe -oms.ApiOnly
2017-12-19 12:14:22.0363 Model directory: models/bin
2017-12-19 12:14:22.0400 Starting at localhost:4040
2017-12-19 12:14:22.0402 To finish press Ctrl+C

To start openM++ web-service on Linux:

  • download and unpack openM++, i.e.:
wget http://sourceforge.net/projects/ompp/files/2018_02_05/openmpp_centos_20180205.tar.gz
tar xzf openmpp_centos_20180205.tar.gz
  • run oms executable:
cd openmpp_centos_20180205/
bin/oms -oms.ApiOnly
2017-12-19 12:14:22.0363 Model directory: models/bin
2017-12-19 12:14:22.0400 Starting at localhost:4040
2017-12-19 12:14:22.0402 To finish press Ctrl+C

OpenM++ web-service configuration

Oms default configuration options can be overwritten by command-line arguments or ini-file. For example:

oms -l :7070
oms -l :7070 -oms.ApiOnly
oms -oms.ApiOnly -oms.ModelDir ../some/dir
oms -oms.ApiOnly -OpenM.LogToConsole false -OpenM.LogToFile
oms -oms.ApiOnly -OpenM.LogToConsole false -OpenM.LogToFile -OpenM.LogUseDailyStamp
oms -ini oms.ini

Following options supported by oms:

-oms.Listen:       address to listen, default: localhost:4040
-l:                address to listen (short form of -oms.Listen)
-oms.RootDir:      root directory, default: current directory
-oms.ModelDir:     models directory, if relative then must be relative to root directory, default: models/bin
-oms.LogRequest:   if true then log HTTP requests
-oms.ApiOnly:      if true then API only web-service, no UI
-oms.MaxRowCount:  max number of rows to select for parameter or output table values, default: 100
-oms.Languages:    comma-separated list of supported UI languages
-oms.CodePage:     code page to convert source file into utf-8, e.g.: windows-1252
-oms.DoubleFormat: format to convert float or double value to string, default: %.15g

-OpenM.OptionsFile:      path to ini-file
-ini:                    path to ini-file (short of -OpenM.OptionsFile)
-OpenM.LogToConsole:     if true then log to standard output, default: true
-v:                      if true then log to standard output (short of -OpenM.LogToConsole)
-OpenM.LogToFile:        if true then log to file
-OpenM.LogFilePath:      path to log file, default = current/dir/exeName.log
-OpenM.LogUseTs:         if true then use time-stamp in log file name
-OpenM.LogUsePid:        if true then use pid-stamp in log file name
-OpenM.LogUseDailyStamp: if true then use daily-stamp in log file name
-OpenM.LogNoMsgTime:     if true then do not prefix log messages with date-time
-OpenM.LogSql:           if true then log sql statements into log file

There are many common options, e.g.: -OpenM.LogToFile which can be used with any openM++ executable: models, complier, dbcopy. Please check openM++ ini-files and command-line arguments page.

Note: We recommend to use normal Windows command line cmd.exe. If you are using Windows PowerShell then it may be necessary to put "quotes" around command line options, e.g:

oms.exe "-oms.ApiOnly"

Oms as "pure" web-service vs "full" web-UI

By default oms.exe started in "full" web-UI mode. That means it handles web-service requests and web-UI content from ./html sub-directory. If you want only "pure" web-service mode without UI then use:

oms -oms.ApiOnly

Oms directory structure

Following directory structure expected by default:

./         -> "root" directory, by default it is current directory
    html/        -> web-UI directory with HTML, js, css, images, etc.
    log/         -> recommended log files directory
    models/bin/  -> default model.exe and model.sqlite directory

If you don't have html/ directory and don't want web-UI then:

oms -oms.ApiOnly

If you want to use log file and no console messages:

oms -OpenM.LogToConsole=false -OpenM.LogToFile
oms -OpenM.LogToConsole=false -OpenM.LogFilePath log/oms.log

If you want to use "daily" log files:

oms -OpenM.LogUseDailyStamp -OpenM.LogToFile 
oms -OpenM.LogUseDailyStamp -OpenM.LogFilePath log/oms.log

Arguments for web-service methods

Following arguments used in web-service methods below:

 :model - model digest or model name

Example of method:

GET /api/model/:model

Call example:

http://localhost:4040/api/model/f5024ac32c4e8abfc696a0f925141c95
http://localhost:4040/api/model/modelOne

Model can be identified by digest or by model name. It is recommended to use digest because it is uniquely identifies model. It is possible to use model name, which is more human readable than digest, but if there are multiple models with same name in database than result is undefined.

 :run - model run digest or run name

Example of method:

GET /api/model/:model/run/:run/status

Call example:

http://localhost:4040/api/model/modelOne/run/modelOne_first_run/status
http://localhost:4040/api/model/modelOne/run/d06f4a0a45a9514c22593025e489f933/status

Model run can be identified by run digest or by run name. It is recommended to use digest because it is uniquely identifies model run. It is possible to use name, which is more human readable than digest, but if there are multiple runs with same name in database than result is undefined.

 :lang - language code

Example of method:

GET /api/model/:model/text/lang/:lang

Call example:

http://localhost:4040/api/model/modelOne/text/lang/EN
http://localhost:4040/api/model/modelOne/text/lang/en_US

Language code can be a model language (ex.: EN, FR) or any MIME language (see BCP47 or RFC3282). If no language explicitly specified then Accept-Language header is used (supplied by browser).

Result returned in best matched language supported by model. For example for en_US result is model language EN, if model supported EN language. If no such language then result is in default model language or can be empty.

 :set - workset name

Method examples:

GET  /api/model/:model/workset/:set/status
POST /api/model/:model/workset/:set/readonly/:val

Call examples:

http://localhost:4040/api/model/modelOne/workset/modelOne_set/status
curl -v -X POST http://localhost:4040/api/model/modelOne/workset/modelOne_set/readonly/1

Workset is a set of model input parameters (a.k.a. "scenario" input) and it used to run the model Each model workset uniquely identified by name.


<metadesc>OpenM++: open source microsimulation platform</metadesc>