Help Resources PIFOP Usage Getting Started Running a Solver Collaboration and Sharing Options Supported Languages and Files Working with Google Sheets Markdown + LaTeX Project Answer Project Collections List of Examples Provisioned Optimization Server Enterprise Plan and Subscription Keys Hosting an Optimization Server Introduction to Optimization Server Hosting Hosting an Opt-Server Configure Commands Basic Command Configurations Security Best Practices Manage Users List of Configuration Options PIFOP FUNCTIONS Introduction to PIFOP Functions Create and Manage PIFOP Functions PIFOP Functions REST API AMPL Basics Program Structure Model Entities Set Expressions Indexing Expressions Data Assignment Basic Commands More AMPL References Attributes of Sets, Parameters and Variables Printing Commands and Options

PIFOP Functions REST API

PIFOP Functions is an experimental feature. Contact us if you would like to try it out.

Introduction

PIFOP Functions can be executed using virtually any programming language via one of our APIs. This page describes the PIFOP Function REST API, but we provide easier to use client APIs for the following programming languages:

JavaScript
Python — comming soon

We strongly recommend that you use one of the above libraries if you are programming in one of these languages. If not, you can interact with our REST API directly via whatever language you are working with. Keep reading to learn more.

General Remarks

Making API Requests

Required headers: the Authorization header is required for all API requests — see below.
Request Body: with the exception of the input upload API call, in general the API does not expect anything in the body of the requests. All of the data necessary for the API calls are passed in the URL path or query string.
Response Body: usually a JSON, with the exception of the output download API call that returns the raw contents of a file.

Authentication

We use API keys to authenticate requests. Function authors can view and manage their API keys in the Functions management page.

Authentication is performed via HTTP Bearer Auth. Provide the API key in the Authorization header, e.g.:

Authorization: Bearer apikey_MGMK1j5VFu3dTvxOZ3CEd2kNRIYeG4VchcWSehKjCVYDeA79

Use the Function Master key for administrative operations, such as generating a new API key. The Master key starts with master.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Common URL Parameters

Some URL parameters appear in almost all endpoints. See below an endpoint example and the meaning of each of its highlighted parts.

POST func.pifop.com/$func_author/$func_id/executions/$exec_id

$func_author — PIFOP username of the author of the function. Example: david
$func_id — id of the function, unique across the functions of the same author, defined in the Function configuration file. Example: tsp_solver
$exec_id — id of an execution, unique across the existing executions of the same function. Example: exec_ABC1234

The Execution Object

Execution is a short-lived type of object that represents a Function execution. From the moment it is initialized to the moment it ends, an Execution will usually go through the following states: pending — running — ended.

A typical Function execution will require you to perform the following actions:

Initialize an Execution. An Execution is always initialized in the pending state. Use the returned execution id to perform the subsequent actions.
Upload input files. This can only be performed during the pending state.
Start the Execution.
Retrieve output files. This can only be performed during the ended state
Terminate the Execution. Essentially destroys the Execution.

At any moment during its lifetime, you can terminate the Execution, which will delete all of the data associated with it.

Object Properties

id — id of the Execution.
func_author — author of the Function associated with this Execution.
func_id — id of the Function associated with this Execution.
status — Execution status:
- "pending" — Execution hasn't started yet. Input can still be uploaded.
- "running" — Execution is currently in progress.
- "ended" — Execution has ended. See end_reason below.
end_reason — Reason why the Execution ended:
- "normal" — The process has ended normally, i.e., without being killed due to usage limits.
- "out-of-memory" — The process was ended due to the memory limit associated with the API key.
- "timeout" — The process was ended due to the time limit associated with the API key.
init_date — date it has been initialized.
start_date — date it has started.
end_date — date it has ended.
log — the log of the Execution is essentially what the execution prints out to the terminal. When retrieving the Execution object, you have the option to include this property or not. Learn more below.

New Execution

POST func.pifop.com/$func_author/$func_id/executions

Response body — a new Execution object.

Example:

curl -X POST https://func.pifop.com/joe/tsp/executions \
     -H "Authorization: Bearer apikey_ABC123"

Upload Input File

POST func.pifop.com/$func_author/$func_id/executions/$exec_id/input/$input_id

$input_id — id of the input, defined in the Function configuration file.
Request body — the input file content.
Response body — JSON containing input info.

Example:

curl -X POST https://func.pifop.com/joe/tsp/executions/exec_ABC1234/input/coords \
     -H "Authorization: Bearer apikey_ABC123" \
     -d "150, 254, 145, 222, 478, 644, 98, 51"

Start Execution

POST func.pifop.com/$func_author/$func_id/executions/$exec_id/start

Response body — the Execution object.

Example:

curl -X POST https://func.pifop.com/joe/tsp/executions/exec_ABC1234/start \
     -H "Authorization: Bearer apikey_ABC123"

Retrieve Execution Info

GET func.pifop.com/$func_author/$func_id/executions/$exec_id
?include_log=$include_log

$include_log — optional boolean query parameter. If false, the execution log is not included in the response. The execution log is essentially what the execution prints out to the terminal. The main benefit of of setting include_log to false is a posible improvement on the network performance of your application, as less data will have to be transfered. Default: true.
Response body — the Execution object.

Example:

curl https://func.pifop.com/joe/tsp/executions/exec_ABC1234 \
     -H "Authorization: Bearer apikey_ABC123"

Download Output File

GET func.pifop.com/$func_author/$func_id/executions/$exec_id/output/$output_id

$output_id — id of the output, defined in the Function configuration file.
Response body — the content of the output file.

Example:

curl https://func.pifop.com/joe/tsp/executions/exec_ABC1234/output/result \
     -H "Authorization: Bearer apikey_ABC123"

Stop Execution

POST func.pifop.com/$func_author/$func_id/executions/$exec_id/stop

Response body — the Execution object.

Example:

curl -X POST https://func.pifop.com/joe/tsp/executions/exec_ABC1234/stop \
     -H "Authorization: Bearer apikey_ABC123"

Terminate Execution

DELETE func.pifop.com/$func_author/$func_id/executions/$exec_id

Response body — the Execution object.

Example:

curl -X DELETE https://func.pifop.com/joe/tsp/executions/exec_ABC1234 \
     -H "Authorization: Bearer apikey_ABC123"

The Function Object and API Keys

Get Function Info

GET func.pifop.com/$func_author/$func_id

Response body — a Function object.

Example:

curl https://func.pifop.com/joe/tsp \
     -H "Authorization: Bearer master_ABC123"

Generate API Key

POST func.pifop.com/$func_author/$func_id/api_keys
?key_name=$name
&max_memory=$max_memory
&max_time=$max_time
&max_executions=$max_executions

$key_name — required name of the new key.
$max_memory — optional max memory. By default, no limit is set.
$max_time — optional max time. By default, no limit is set.
$max_executions — optional max simultaneous executions. By default, no limit is set
Response body — a new API key.

Example:

curl -X POST https://func.pifop.com/joe/tsp/api_keys?key_name=david&max_executions=2 \
     -H "Authorization: Bearer master_ABC123"

Delete API Key

DELETE func.pifop.com/$func_author/$func_id/api_keys/$key_name

$key_name — required name of the key to delete.
Response body — deleted API key.

Example:

curl -X DELETE https://func.pifop.com/joe/tsp/api_keys/david \
     -H "Authorization: Bearer master_ABC123"

Terms and Privacy Help Pricing About Blog Contact us Server Status Twitter LinkedIn