HTTP API
OpenSEFA.jl provides a RESTful HTTP API for solving data reconciliation problems. This enables integration with web applications, remote clients, and other programming languages.
Starting the Server
To start the HTTP server, run:
$ julia --project -e "using OpenSEFA; start_server()"If successful, you should see output similar to:
____
/ __ \_ ____ ______ ____ ____
/ / / / |/_/ / / / __ `/ _ \/ __ \
/ /_/ /> </ /_/ / /_/ / __/ / / /
\____/_/|_|\__, /\__, /\___/_/ /_/
/____//____/
[ Info: 📦 Version 1.10.2 (2026-04-18)
[ Info: ✅ Started server: http://0.0.0.0:8080
[ Info: 📖 Documentation: http://0.0.0.0:8080/docs
[ Info: 📊 Metrics: http://0.0.0.0:8080/docs/metrics
[ Info: Listening on: 0.0.0.0:8080, thread id: 1By default, the server listens on 0.0.0.0:8080. You can customize the host and port in the server configuration.
API Endpoints
Health Check
Endpoint: GET /health
Check the server's operational status, including uptime and request statistics.
Example Request:
curl http://localhost:8080/healthExample Response:
{
"requests": {
"average time (sec)":0.87,
"max time (sec)":2.34,
"total": 12
},
"uptime (sec)": 45.68
}Response Fields:
uptime (sec): Time since server startedrequests.total: Total number of requests processedrequests.max time (sec): Maximum request processing timerequests.average time (sec): Average request processing time
Solve Problem
Endpoint: POST /solve
Solve a data reconciliation problem specified by JSON content. Send the complete problem definition in the request body.
Example Request:
curl -X POST http://localhost:8080/solve \
-H "Content-Type: application/json" \
-d '{
"content": {
"name": "Simple Example",
"variables": [
{
"name": "F1_mass_N1",
"type": "MeasuredVariable",
"value": 1.0,
"uncertainty": 0.1,
"is_transfer_coefficient": false
},
{
"name": "F2_mass_N1",
"type": "UnmeasuredVariable",
"is_transfer_coefficient": false
},
{
"name": "F3_mass_N1",
"type": "MeasuredVariable",
"value": 2.0,
"uncertainty": 0.3,
"is_transfer_coefficient": false
}
],
"equations": [
{
"constant_term": {"value": 0},
"linear_terms": [
{"name": "F1_mass_N1", "factor": 1},
{"name": "F3_mass_N1", "factor": 1},
{"name": "F2_mass_N1", "factor": -1}
],
"bilinear_terms": []
}
],
"solver": "JuMP"
}
}'Response Format:
Success response (HTTP 200):
{
"JuMP optimizer": "IpoptMathOptInterfaceExt.Optimizer",
"JuMP solve time (s)": 0.006921052932739258,
"JuMP status": "LOCALLY_SOLVED",
"Solve time (s)": 0.008294383,
"equations_value": {
"1": -4.694022948115162e-13
},
"globality_proven": true,
"objective_value": 1.2297865261038426e-17,
"residual_value": 4.694e-13,
"status": "FEASIBLE",
"uncertainties": {
"F1_mass_N1": 0.1,
"F2_mass_N1": 0.31622776601683794,
"F3_mass_N1": 0.3
},
"unobservable unmeasured variables": [
"0 unobservable unmeasured variables identified (not removed): ",
[]
],
"variables_value": {
"F1_mass_N1": 1.000000000133192,
"F2_mass_N1": 3.000000001106876,
"F3_mass_N1": 2.000000000973215
},
"version": "0.18.0"
}Error response (HTTP 400/500):
{
"message": "500: Internal Server Error"
}JSON Problem Format
The JSON format for defining problems follows this schema:
{
"name": "Problem Name",
"variables": [
{
"name": "variable_name",
"type": "MeasuredVariable|UnmeasuredVariable|FixedVariable",
"value": 1.0, // Required for Measured/Fixed
"uncertainty": 0.1, // Required for Measured
"is_transfer_coefficient": false // Optional, default: false
}
],
"equations": [
{
"constant_term": {"value": 0.0},
"linear_terms": [
{"name": "variable_name", "factor": 1.0}
],
"bilinear_terms": [ // Optional
{
"name1": "var1",
"name2": "var2",
"factor": 0.5
}
]
}
],
"solver": "JuMP" // Alternative: "Default"
}Variable Types
- MeasuredVariable: Known value with uncertainty (requires
valueanduncertainty) - UnmeasuredVariable: Unknown value to be determined by optimization
- FixedVariable: Known value without uncertainty (requires
value)
Equation Structure
Each equation represents a constraint of the form:
constant_term + sum(linear_terms) + sum(bilinear_terms) = 0- linear_terms: Terms of the form
factor * variable - bilinear_terms: Terms of the form
factor * var1 * var2
Integration with OpenSEFA editor
OpenSEFA.jl can be integrated with the OpenSEFA editor. If you are interested in the editor source code, please contact Matplus GmbH. A valid JointJS+ license must be held.
Setup
- Switch to the OpenSEFA editor project
- Create a
config.jsfile in the project root:
window.__ENV__ = {
EDA_HOST: "http://0.0.0.0:8080",
SOLVER_TOKEN: ""
};- Build the editor:
npm run build
Workflow
- Start the OpenSEFA.jl HTTP server
- Launch the editor:
npm run dev - Create or load a model in the editor
- Click the "Solve" button to send a request to the Julia backend
- View results in the editor interface
When deploying in production, ensure proper CORS configuration and authentication tokens are set.
Client Examples
Python Client
import requests
import json
# Define the problem
problem = {
"content": {
"name": "Python Example",
"variables": [
{"name": "F1", "type": "MeasuredVariable", "value": 1.0, "uncertainty": 0.1},
{"name": "F2", "type": "UnmeasuredVariable"},
{"name": "F3", "type": "MeasuredVariable", "value": 2.0, "uncertainty": 0.3}
],
"equations": [
{
"constant_term": {"value": 0},
"linear_terms": [
{"name": "F1", "factor": 1},
{"name": "F3", "factor": 1},
{"name": "F2", "factor": -1}
],
"bilinear_terms": []
}
],
"solver": "JuMP"
}
}
# Send request
response = requests.post(
"http://localhost:8080/solve",
headers={"Content-Type": "application/json"},
data=json.dumps(problem)
)
# Parse response
if response.status_code == 200:
result = response.json()
print(json.dumps(result, indent=2))
else:
print(f"Error: {response.json()['message']}")JavaScript Client
async function solveProblem() {
const problem = {
content: {
name: "JavaScript Example",
variables: [
{ name: "F1", type: "MeasuredVariable", value: 1.0, uncertainty: 0.1 },
{ name: "F2", type: "UnmeasuredVariable" },
{ name: "F3", type: "MeasuredVariable", value: 2.0, uncertainty: 0.3 }
],
equations: [
{
constant_term: { value: 0 },
linear_terms: [
{ name: "F1", factor: 1 },
{ name: "F3", factor: 1 },
{ name: "F2", factor: -1 }
],
bilinear_terms: []
}
],
solver: "JuMP"
}
};
try {
const response = await fetch("http://localhost:8080/solve", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(problem)
});
const result = await response.json();
if (response.ok) {
console.log("Objective:", result.objective_value);
console.log("Variables:", result.variables_value);
} else {
console.error("Error:", result.message);
}
} catch (error) {
console.error("Request failed:", error);
}
}
solveProblem();Error Handling
The API returns appropriate HTTP status codes:
- 200 OK: Request successful, solution found
- 500 Internal Server Error: Solver failed or internal error
Error responses include a message field with details:
{
"message": "500: Internal Server Error"
}Performance Considerations
- The server processes requests synchronously
- For large models, requests may take several seconds to minutes
- Consider implementing client-side timeouts (recommended: 60-300 seconds)
- Monitor the
/healthendpoint for server performance metrics
Next Steps
- Review Examples for problem formulations
- Check the API Reference for programmatic Julia usage
- See Getting Started for installation details