Making predictions

ScienceOps provides an API for querying models. Querying a model consists of sending in structure data to the model, allowing the model to process the data and make some sort of prediction using it, and then getting that information back from the model. This page will walk you through the aspects of using the ScienceOps Prediction API.

API Specification

Making a prediction on ScienceOps is done via a POST request. For detailed information about making a request, please see here:

  • REST API: Send in a single piece of data for processing
  • Bulk API: Process multiple datapoints simultaneously

The remainder of this document will cover some commonly asked questions about the API.

Model Endpoints

Each model deployment receives its own endpoint. This endpoint can be queries via an HTTP request. Endpoints are structured like the following:

/<user_name>/models/<model_name>/

So for example, if the user "kermit" deployed a model called "HelloWorld", then endpoint would be: /kermit/models/HelloWorld/.

When a new version of a model is deployed, the new model is read into memory and once it's online it will be "hot-swapped" into the endpoint. This means there is zero downtime between deployments.

Authentication

ScienceOps uses Basic Auth for authenticating predictions, or API requests. To authenticate with Basic Auth, provide an HTTP header with name "Authorization" and value "Basic " + (your base64 encoded apikey)". For example, in the cURL request below you can see the HTTP headers printed out for my request which includes "Authorization: Basic a2VybWl0OmFiY2QxMjM0NTY3ODk=".

curl -vX POST -H "Content-Type: application/json" \
  --user kermit:abcd123456789 \
  --data '{"name":"hank"}' \
  https://sandbox.yhathq.com/kermit/models/HelloWorld/
*   Trying 52.5.5.183...
* Connected to sandbox.yhathq.com (52.5.5.183) port 443 (#0)
* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
* Server certificate: *.yhathq.com
* Server certificate: COMODO RSA Domain Validation Secure Server CA
* Server certificate: COMODO RSA Certification Authority
* Server certificate: AddTrust External CA Root
* Server auth using Basic with user 'kermit'
> POST /kermit/models/HelloWorld/ HTTP/1.1
> Host: sandbox.yhathq.com
> Authorization: Basic a2VybWl0OmFiY2QxMjM0NTY3ODk=
> User-Agent: curl/7.43.0
> Accept: */*
> Content-Type: application/json
> Content-Length: 15

Most HTTP libraries should have a standard way of making a Basic Auth request. For example, in Ruby it would look like this:

require 'net/http'
require 'uri'
require 'json'

url = URI('https://sandbox.yhathq.com/kermit/models/HelloWorld/')
# Create new request
req = Net::HTTP::Post.new(url.path)
# Encode basic auth
req.basic_auth "kermit", "abcd123456789"

JSON structure

ScienceOps model endpoint accept 2 data formats: json and ldjson (or line-delimited JSON). Typically you'll be working with the json standard.

JSON

Using the JSON format, ScienceOps will serialize the data and feed it directly into the model that you're calling.

Python models

For Python models, data is serialized using the json.dumps function from the built-in json library. This means your data will end up in the model as either a Python list or a Python dictionary data-type.

R models

For R models, data is serialized using the jsonlite::toJSON function. Serialization can seem a bit strange at first given R's "vectorization-first", but it's very convenient (and powerful) for performing complex analysis and linear algebra. As a result of the vectorization, you might see vectorized JSON data returned from models. For example:

{
  "result": {
    "name": ["Hello Kermit!"]
  },
  "yhat_id": "c747df0729df439fac632e45146c5993"
}

LDJSON

For processing multiple predictions in a single API request, you can use the LDJSON format. This allows you to send in a stream of data that contains line-delimited rows of JSON. For example:

{"name": "Kermit"}
{"name": "Miss Piggy"}
{"name": "Fozzie"}
{"name": "Gonzo"}

To indicate you're sending LDJSON, add the ?bulk=true query parameter to your request.

echo '{"name": "Kermit"}
{"name": "Miss Piggy"}
{"name": "Fozzie"}
{"name": "Gonzo"}' | \
 curl -X POST -H "Content-Type: application/json" \
   --user greg:77ce101c3c7f24cc084e691935adaedb \
   --data @- \
   "https://sandbox.yhathq.com/greg/models/HelloWorld/?bulk=true"
# {"bulk_id":"ca7de9e4283072ebfd7aee4edf2a2fad","end_time":"2016-09-22 16:22:45.317941249 +0000 UTC","result":{"greeting":"Hello Kermit!"},"start_time":"2016-09-22 16:22:45.317369057 +0000 UTC","version":21,"yhat_id":"0637ac66ff153ac16f4872a6cf2606d7","yhat_model":"HelloWorld"}
# {"bulk_id":"ca7de9e4283072ebfd7aee4edf2a2fad","end_time":"2016-09-22 16:22:45.318448998 +0000 UTC","result":{"greeting":"Hello Miss Piggy!"},"start_time":"2016-09-22 16:22:45.31797084 +0000 UTC","version":21,"yhat_id":"3a10782a7806cb04d11036de37eed194","yhat_model":"HelloWorld"}
# {"bulk_id":"ca7de9e4283072ebfd7aee4edf2a2fad","end_time":"2016-09-22 16:22:45.31890956 +0000 UTC","result":{"greeting":"Hello Fozzie!"},"start_time":"2016-09-22 16:22:45.318475573 +0000 UTC","version":21,"yhat_id":"09240da28fbd5fa85dbb51c44e2b92b6","yhat_model":"HelloWorld"}
# {"bulk_id":"ca7de9e4283072ebfd7aee4edf2a2fad","end_time":"2016-09-22 16:22:45.319350137 +0000 UTC","result":{"greeting":"Hello Gonzo!"},"start_time":"2016-09-22 16:22:45.318931912 +0000 UTC","version":21,"yhat_id":"39bb8212c28486de068d8035e2c6bf89","yhat_model":"HelloWorld"}

results matching ""

    No results matching ""