home > docs > tutorials > si_pasteur_restful

System Integrator tutorial for access to the Pasteurization models via the LIBPF® RESTful Model User API

Introduction

Intended audience

System integrators who want to develop solutions based on the modeling of industrial continuous processes with the LIBPF® enabling technology.

Scope

Give a step-by-step tutorial and a reference for the usage of the Pasteurization models through the RESTful Model User API.

Prerequisites

Basic knowledge of the Pasteurization model and process (see references).

Basic knowledge of shell terminal commands or other tools suitable to run GET / POST / PUT / DELETE commands through HTTP protocol.

RESTful API access

The RESTful API can be basically accessed with any Internet browser by typing the addresses as usual URLs in the browser address field; but browsers only support the HTTP “GET” request - whenever a POST, PUT or DELETE verb must be used, it is best to use a more flexible tool. The sample commands use the cURL utility, a command-line tool for transferring data using various protocols. Use your preferred tools, there are several browser extensions (HttpRequester, REST easy …) and windows graphical tools (fiddler2, wfetch) you can use.

The sample commands use the https://simevo.com/api/process/pasteurize/ URL as service (that’s the location of the publicly accessible demo service); please replace this URL with the name of your actual service.

Model life cycle

To get a list of all available types run:

curl -k -X GET https://simevo.com/api/process/pasteurize/types

Or add a destination of the output to actually save it as a text file:

curl -k -X GET https://simevo.com/api/process/pasteurize/types > types.json

You can also try it in your browser accessing the URL https://simevo.com/api/process/pasteurize/types.

This outputs a long list of types and their capabilities. Using “find” functions it is easier to find a specific type with its name and description

An extract of the expected response could be:

{
  "service_uuid": "62e3a255-c1a0-4dea-a650-05b9a4a33aef",
  "types": [
    ...
    {
      "category": "flowsheet",
      "integerOptions": [],
      "instantiable": true,
      "name": "Pasteur",
      "description": "Generic continuous pasteurization process",
      "stringOptions": [
        {
          "enumerator": "processType",
          "name": "processType",
          "value": "HTST15",
          "description": "adjusts temperature and holding time"
        },
        {
          "enumerator": "feedType",
          "name": "feedType",
          "value": "chocolateIceCream",
          "description": "sets a predefined composition for the fluid to be processed"
        }
      ],
      "icon": "Pasteur.svg"
    }
  ]
}

Creation

Create a new case with default settings

curl -k -X -d '' POST https://simevo.com/api/process/pasteurize/cases

Expected response:

{
  "modified_at": 1427880901.18888,
  "case_uuid": "80a73b75-17d2-4bb7-bb69-1c68930b880e",
  "description": "",
  "url": "https://simevo.com/api/process/pasteurize/cases/80a73b75-17d2-4bb7-bb69-1c68930b880e",
  "service_uuid": "62e3a255-c1a0-4dea-a650-05b9a4a33aef",
  "created_at": 1427880901,
  "tag": "",
  "type": "Pasteur"
}

Create a new case with specified type, tag, description and options

curl -k -X POST -d '{"type":"Pasteur",
                     "tag":"case123",
                     "description":"case with 1 2 3 times",
                     "stringOptions": {
                       "processType":"HTST15",
                       "feedType":"chocolateIceCream"
                      } }' https://simevo.com/api/process/pasteurize/cases

Or, if the ‘{ … }’ string is packed as a json file (case_descriptor.json):

cat > case_descriptor.json
{
  "type":"Pasteur",
  "tag":"case123",
  "description":"case with 1 2 3 times",
  "stringOptions": {
    "processType":"HTST15",
    "feedType":"chocolateIceCream"
  }
} 
^d
curl -k -X POST -d @case_descriptor.json https://simevo.com/api/process/pasteurize/cases

or:

cat case_descriptor.json | curl -k -X POST -d - https://simevo.com/api/process/pasteurize/cases

For the supported types, and option values, interpret the output of the types command above as detailed in the “Instantiating and using a Model” chapter of the LIBPF® Model User API documentation.

Expected response:

{
  "modified_at": 1427880852.19795,
  "case_uuid": "25c92f85-74b2-4022-9ec0-fbbeb6266ac4",
  "description": "case with 1 2 3 times",
  "url": "https://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4",
  "service_uuid": "62e3a255-c1a0-4dea-a650-05b9a4a33aef",
  "created_at": 1427880852,
  "tag": "case123",
  "type": "Pasteur"
}

Pay attention to the response which contain an “url” string associated to the case handle (i.e. “/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4” : the handle is 25c92f85-74b2-4022-9ec0-fbbeb6266ac4). You should annotate that value for further model accesses.

Database purge

To delete (purge) all database saved cases run:

curl -k -X DELETE  https://simevo.com/api/process/pasteurize/cases

Expected response:

{"service_uuid": "62e3a255-c1a0-4dea-a650-05b9a4a33aef"}

Deletion

To delete a specific saved case run:

curl -k -X DELETE  https://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4

replace the code 25c92f85-74b2-4022-9ec0-fbbeb6266ac4 with the handle you obtained during the case creation.

Model usage

Remark: All variable inside the model are input, calculated and returned using the SI of units of measurement.

Set variables and calculate

To set one or more input variables and immediately re-calculate the model, POST on the case handle, with a JSON-encoded array of variable/values in the request:

curl -k -X POST -d '{ 
  "controlled": [ {
     "variable": "coolT",
     "end": 274.15 
   }] }' https://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4

replace the number 25c92f85-74b2-4022-9ec0-fbbeb6266ac4 with the handle you obtained during the case creation.

Or, if the ‘{ … }’ string is packed as a json file (changes.json):

cat > changes.json
{ "controlled": [
  { 
    "variable": "coolT", 
    "end": 274.15
  } ] }
^d
curl -k -X POST -d @changes.json https://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4

replace the number 25c92f85-74b2-4022-9ec0-fbbeb6266ac4 with the handle you obtained during the case creation.

Or:

cat changes.json | curl -k -X POST -d - https://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4

Expected response:

{"message": "success", "error": 0}

Remark: the variable setting actually call the model re-calculation, so it is best to set multiple variables at once to avoid multiple re-calculation:

curl -k -X POST -d '{ "controlled": 
  [{ "variable": "S01.T", "end": 300 },
   { "variable": "RX:reactions[0].z", "end": 0.95 } 
  ] }' https://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4

Calculate

To force the model calculation without setting any variable, POST the on the case handle, without empty data in the request:

curl -k -X POST -d '' https://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4

replace the number 25c92f85-74b2-4022-9ec0-fbbeb6266ac4 with the handle you obtained during the case creation.

Expected response:

{
  "modified_at": 1427881237.10185,
  "case_uuid": "25c92f85-74b2-4022-9ec0-fbbeb6266ac4",
  "description": "",
  "url": "https://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4",
  "service_uuid": "62e3a255-c1a0-4dea-a650-05b9a4a33aef",
  "created_at": 1427881236.0,
  "tag": "",
  "type": "Pasteur"
}

Get results

Each input / output variable is individually accessible with a GET request:

curl -k -X GET https://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4/quantities/coolT

replace the number 25c92f85-74b2-4022-9ec0-fbbeb6266ac4 with the handle you obtained during the case creation.

You can also try it in your browser accessing the URL https://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4/quantities/coolT.

Expected response:

{
  "service_uuid": "62e3a255-c1a0-4dea-a650-05b9a4a33aef",
  "value": 278.15,
  "path": "coolT"
}

It is possible to dump the whole model in a txt format:

curl -k -X GET https://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4/txt

replace the number 25c92f85-74b2-4022-9ec0-fbbeb6266ac4 with the handle you obtained during the case creation.

Or add a destination of the output to actually save it as a text file:

curl -k -X GET https://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4/txt > myOutputFile.txt

You can also try it in your browser accessing the URL https://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4/txt.

Model tools

Homotopy

Not yet supported through RESTful API

curl -k -X POST -d '{ "controlled": [
  { 
    "variable": "S01.T", 
    "start": 200 , 
    "end": 300
  }, { 
    "variable": "RX:reactions[0].z",
    "start": 0.27 , 
    "end": 0.95 
  } ] }' https://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4/homotopy

replace the number 25c92f85-74b2-4022-9ec0-fbbeb6266ac4 with the handle you obtained during the case creation.

Or, if the ‘{ … }’ string is packed as a json file (changes.json):

cat > changes.json
{ "controlled": [
  { 
    "variable": "S01.T", 
    "start": 200 , 
    "end": 300
  }, { 
    "variable": "RX:reactions[0].z",
    "start": 0.27 , 
    "end": 0.95 
  } ] }
^d
curl -k -X POST -d @changes.json https://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4/homotopy

Or:

cat changes.json | curl -k -X POST -d - https://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4/homotopy

Sensitivity

Not yet supported through RESTful API

curl -k -X GET -d '{
  "controlled": [
    {
      "variable": "S01.T",
      "start": 200,
      "end": 300
    },
    {
      "variable": "RX:reactions[0].z",
      "start": 0.27,
      "end": 0.95
    }
  ],
  "monitored": [
    { "variable": "S01.P" },
    { "variable": "RX.duty" } 
  ] }' https://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4/sensitivity

replace the number 25c92f85-74b2-4022-9ec0-fbbeb6266ac4 with the handle you obtained during the case creation.

Or, if the ‘{ … }’ string is packed as a json file (sensitivity.json):

cat > sensitivity.json
{
  "controlled": [
    {
      "variable": "S01.T",
      "start": 200,
      "end": 300
    },
    {
      "variable": "RX:reactions[0].z",
      "start": 0.27,
      "end": 0.95
    }
  ],
  "monitored": [
    { "variable": "S01.P" },
    { "variable": "RX.duty" } 
  ]
}
^d
curl -k -X POST -d @sensitivity.json https://simevo.com/api/process/pasteurize/cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4/sensitivity

Or:

cat sensitivity.json | curl -k -X POST -d - /cases/25c92f85-74b2-4022-9ec0-fbbeb6266ac4/sensitivity

Pasteurization Model references

LIBPF® references