REST web service for scoring PMML models.
- Full support for PMML specification versions 3.0 through 4.2. The evaluation is handled by the [JPMML-Evaluator] (https://github.com/jpmml/jpmml-evaluator) library.
- Simple and powerful REST API:
- Model deployment and undeployment.
- Model evaluation in single prediction, batch prediction and CSV prediction modes.
- Model metrics.
- High performance and high throughput:
- Sub-millisecond response times.
- Thread safe.
- Open, extensible architecture for easy integration with proprietary systems and services:
- User authentication and authorization.
- Metrics dashboards.
The project requires Java 1.7 or newer to run.
Enter the project root directory and build using [Apache Maven] (http://maven.apache.org/):
mvn clean install
The build produces an executable uber-JAR file server/target/server-executable-1.1-SNAPSHOT.jar
. The main class of the Openscoring application org.openscoring.server.Main
can be automatically loaded and executed by specifying the -jar
command-line option:
java -jar server-executable-1.1-SNAPSHOT.jar
By default, the REST web service is started at [http://localhost:8080/openscoring] (http://localhost:8080/openscoring/). The main class accepts a number of configuration options for URI customization and other purposes. Please specify --help
for more information.
Additionally, the build produces an executable uber-JAR file client/target/client-executable-1.1-SNAPSHOT.jar
which contains a number of command-line client applications.
Model collection REST API endpoints:
HTTP method | Endpoint | Required role(s) | Description |
---|---|---|---|
GET | /model | - | Get all models |
GET | /model/metrics | admin | Get the metrics of all models |
POST | /model | admin | Deploy a model |
Model REST API endpoints:
HTTP method | Endpoint | Required role(s) | Description |
---|---|---|---|
PUT | /model/${id} | admin | Deploy a model |
GET | /model/${id} | admin | Download a model |
GET | /model/${id}/metrics | admin | Get the metrics of a model |
GET | /model/${id}/schema | - | Get the data schema information of a model |
POST | /model/${id} | - | Evaluate a model in "single prediction" mode |
POST | /model/${id}/batch | - | Evaluate a model in "batch prediction" mode |
POST | /model/${id}/csv | - | Evaluate a model is CSV prediction mode |
DELETE | /model/${id} | admin | Undeploy a model |
Some REST API endpoints require privileged access. By default, the Openscoring application grants the "admin" role to all HTTP requests that originate from the local network address.
Gets the list of all models.
The response body is a JSON serialized form of a list of org.openscoring.common.ModelResponse
objects.
Sample cURL invocation:
curl -X GET http://localhost:8080/openscoring/model
Creates or updates a model.
The request body is a PMML document (indicated by content-type header text/xml
or application/xml
).
The response body is a JSON serialized form of an org.openscoring.common.ModelResponse
object that represents the current state of the model.
Response status codes:
- 200 OK. The model was updated.
- 201 Created. A new model was created.
- 400 Bad Request. The request body is not a valid and/or supported PMML document.
Sample cURL invocation:
curl -X PUT --data-binary @DecisionTreeIris.pmml -H "Content-type: text/xml" http://localhost:8080/openscoring/model/DecisionTreeIris
The example PMML file DecisionTreeIris.pmml
along with example JSON and CSV files is available in the server/etc
directory.
Sample response:
{
"id" : "DecisionTreeIris",
"summary" : "Tree model"
}
Downloads a model.
The response body is a PMML document.
Sample cURL invocation:
curl -X GET http://localhost:8080/openscoring/model/DecisionTreeIris
Takes a snapshot of the metrics of a model.
The response body is a JSON serialized form of a 'com.codahale.metrics.MetricRegistry' object.
Sample cURL invocation:
curl -X GET http://localhost:8080/openscoring/model/DecisionTreeIris/metrics
Sample response:
{
"version" : "3.0.0",
"gauges" : { },
"counters" : {
"records" : {
"count" : 1
}
},
"histograms" : { },
"meters" : { },
"timers" : {
"evaluate" : {
"count" : 1,
"max" : 0.008521913,
"mean" : 0.008521913,
"min" : 0.008521913,
"p50" : 0.008521913,
"p75" : 0.008521913,
"p95" : 0.008521913,
"p98" : 0.008521913,
"p99" : 0.008521913,
"p999" : 0.008521913,
"stddev" : 0.0,
"m15_rate" : 0.19237151525464488,
"m1_rate" : 0.11160702915400945,
"m5_rate" : 0.17797635419760474,
"mean_rate" : 0.023793073545863026,
"duration_units" : "seconds",
"rate_units" : "calls/second"
}
}
}
Gets the data schema information of a model.
The response body is a JSON serialized form of an org.openscoring.common.SchemaResponse
object.
Field definitions are retrieved from the [Mining Schema element] (http://www.dmg.org/v4-2/MiningSchema.html) of the PMML document. The active and group fields relate to the arguments
attribute of the evaluation request, whereas the target and output fields relate to the result
attribute of the evaluation response (see below).
Sample cURL invocation:
curl -X GET http://localhost:8080/openscoring/model/DecisionTreeIris/schema
Sample response:
{
"activeFields" : ["Sepal.Length", "Sepal.Width", "Petal.Length", "Petal.Width"],
"groupFields" : [],
"targetFields" : ["Species"],
"outputFields" : ["Predicted_Species", "Probability_setosa", "Probability_versicolor", "Probability_virginica", "Node_Id"]
}
Evaluates a model in "single prediction" mode.
The request body is a JSON serialized form of an org.openscoring.common.EvaluationRequest
object.
The response body is a JSON serialized form of an org.openscoring.common.EvaluationResponse
object.
Response status codes:
- 200 OK. The evaluation was successful.
- 404 Not Found. The requested model was not found.
- 500 Internal Server Error. The evaluation failed. This is most likely caused by missing or invalid input data.
Sample cURL invocation:
curl -X POST --data-binary @EvaluationRequest.json -H "Content-type: application/json" http://localhost:8080/openscoring/model/DecisionTreeIris
Sample request:
{
"id" : "example-001",
"arguments" : {
"Sepal.Length" : 5.1,
"Sepal.Width" : 3.5,
"Petal.Length" : 1.4,
"Petal.Width" : 0.2
}
}
Sample response:
{
"id" : "example-001",
"result" : {
"Species" : "setosa",
"Predicted_Species" : "setosa",
"Probability_setosa" : 1.0,
"Probability_versicolor" : 0.0,
"Probability_virginica" : 0.0,
"Node_Id" : "2"
}
}
Evaluates a model in "batch prediction" mode.
The request body is a JSON serialized form of a list of org.openscoring.common.EvaluationRequest
objects. The number of list elements is not restricted.
The response body is a JSON serialized form of a list of org.openscoring.common.EvaluationResponse
objects.
Sample cURL invocation:
curl -X POST --data-binary @BatchEvaluationRequest.json -H "Content-type: application/json" http://localhost:8080/openscoring/model/DecisionTreeIris/batch
Evaluates a model in CSV mode.
The request body is a CSV document (indicated by content-type header text/plain
). The data table must contain a data column for every active and group field. The ordering of data columns is not significant. They are mapped to fields by name.
The CSV document must conform to Tab-separated values (TSV) dialect or Microsoft Excel dialect.
The response body is a CSV document. The data table contains a data column for every target and output field.
The first data column can be employed for row identification purposes. It will be copied over from the request data table to the response data table if its name equals to "Id" (the comparison is case insensitive) and the number of rows did not change during the evaluation.
Response status codes:
- 200 OK. The evaluation was successful.
- 400 Bad request. The request body is not a valid and/or supported CSV document.
- 404 Not Found. The requested model was not found.
- 500 Internal Server Error. The evaluation failed. This is most likely caused by missing or invalid input data.
Sample cURL invocation:
curl -X POST --data-binary @input.csv -H "Content-type: text/plain" http://localhost:8080/openscoring/model/DecisionTreeIris/csv
Sample request:
Id,Sepal.Length,Sepal.Width,Petal.Length,Petal.Width
example-001,5.1,3.5,1.4,0.2
example-002,7,3.2,4.7,1.4
example-003,6.3,3.3,6,2.5
Sample response:
Id,Species,Predicted_Species,Probability_setosa,Probability_versicolor,Probability_virginica,Node_Id
example-001,setosa,setosa,1.0,0.0,0.0,2
example-002,versicolor,versicolor,0.0,0.9074074074074074,0.09259259259259259,6
example-003,virginica,virginica,0.0,0.021739130434782608,0.9782608695652174,7
Deletes a model.
Response status codes:
- 204 No Content. The model was deleted.
- 404 Not Found. The requested model was not found.
Sample cURL invocation:
curl -X DELETE http://localhost:8080/openscoring/model/DecisionTreeIris
The following sequence of commands replays the life cycle of a model DecisionTreeIris
:
java -cp client-executable-1.1-SNAPSHOT.jar org.openscoring.client.Deployer --model http://localhost:8080/openscoring/model/DecisionTreeIris --file DecisionTreeIris.pmml
java -cp client-executable-1.1-SNAPSHOT.jar org.openscoring.client.Evaluator --model http://localhost:8080/openscoring/model/DecisionTreeIris -XSepal.Length=5.1 -XSepal.Width=3.5 -XPetal.Length=1.4 -XPetal.Width=0.2
java -cp client-executable-1.1-SNAPSHOT.jar org.openscoring.client.CsvEvaluator --model http://localhost:8080/openscoring/model/DecisionTreeIris --input input.csv --output output.csv --id-column Id
java -cp client-executable-1.1-SNAPSHOT.jar org.openscoring.client.Undeployer --model http://localhost:8080/openscoring/model/DecisionTreeIris
Openscoring is dual-licensed under the [GNU Affero General Public License (AGPL) version 3.0] (http://www.gnu.org/licenses/agpl-3.0.html) and a commercial license.
Please contact [info@openscoring.io] (mailto:info@openscoring.io)