M5ops API for Optimization Models

• M5ops API is a micro-service platform that deploys and manages mathematical optimization models across various algebraic systems.
• It utilizes annotated source code to generate universal JSON recipes, ensuring model reproducibility and abstracting solver details.
• The API leverages stateless REST endpoints, scalable compute workers, and robust authentication to support production-grade optimization workflows.

The M5ops API, as part of the MOS (Mathematical Optimization Service) framework, is a comprehensive micro-service–style platform for the deployment, integration, and management of mathematical optimization models across any algebraic modeling system or solver. Its primary innovation lies in the orchestration of annotated optimization code into a universal JSON-based “recipe,” exposing programmatic and interactive interfaces for both human users and automated systems. The architectural abstraction in M5ops API eliminates ad hoc code and enables optimization models to transition seamlessly to production environments through stateless RESTful endpoints, compositional model definitions, and scalable compute execution (Merrick et al., 2022).

1. Architectural Overview

MOS is designed as a layered system encompassing the following components:

• Backend: Implements a stateless REST API with a persistent database. It manages model recipes, raw and annotated source files, metadata, execution records, streaming logs, and user access permissions.
• Frontend: Provides a single-page web UI for interactive inspection and management of models, permitting users to view inputs, constraints, objectives, and solver status/results without directly editing code.
• Interface Libraries: Current support centers on Python, and the roadmap includes R, Julia, Java, and additional environments. These libraries wrap REST endpoints, presenting models as first-class SDK objects.
• Compute Workers: Execute optimization workloads by invoking algebraic modeling frameworks (e.g., JuMP, cvxpy, GAMS, Pyomo, optmod). Workers assemble solver input structures, launch solvers, and capture output artifacts.

Design principles focus on high-level abstraction (models annotated in source code), model- and solver-agnostic deployment, declarative model “recipes,” extensibility via custom annotations or kernels, and transparency (full pipeline inspection by humans and machines).

2. REST API Core Endpoints

M5ops implements a documented set of RESTful endpoints under /api/v1, mapping optimization lifecycle operations to HTTP verbs and resource URIs. The following table summarizes core operations:

Endpoint	Method	Functionality Description
/api/v1/models	GET	List all registered models (pagination supported)
/api/v1/models	POST	Register model by source upload (annotated file)
/api/v1/models/{model_id}	GET	Retrieve model metadata, recipe, component list
/api/v1/models/{model_id}/components	PUT	Update (override/add) named model components
/api/v1/models/{model_id}/recipe	GET	Download full JSON model recipe
/api/v1/models/{model_id}/executions	POST	Submit a new solve request
/api/v1/models/{model_id}/executions	GET	List all past executions for a model
/api/v1/models/{model_id}/executions/{exec_id}	GET	Retrieve execution status, logs, results
/api/v1/models/{model_id}/executions/{exec_id}/log	GET	Stream/download textual log
/api/v1/models/{model_id}/executions/{exec_id}/result	GET	Download solution data (JSON, CSV, or solver-native formats)

All payloads are UTF-8 encoded JSON, and endpoints accept/return semantically structured objects. Uploads may be multipart or JSON with base64-encoded files.

3. Model Annotation and Recipe Extraction

MOS achieves universal modeling abstraction via source-code annotations, which are parsable language-native comments. Prefixes such as #@ (Python), //@ (C++), and %@ (MATLAB) declare components—e.g., Inputs, Constraints, Objectives, Solvers—directly in code. MOS ingests these files and produces structured recipes. For example, constraints can be annotated as:

#@ Constraint: P_limits #@ Description: Generator active power limits P_limits = [] for gen in network.generators: P_limits.extend([P[gen.index] >= gen.P_min, P[gen.index] <= gen.P_max])

A corresponding JSON recipe would abstract the model as follows:

{ "components": { "inputs": [{ "name":"network", "type":"file"}, ...], "variables": [ ... ], "constraints": [{ "name":"P_limits", ... }], "objectives": [{ "name":"gen_cost_obj", "sense":"min" }], "solver": { "name":"OptSolverINLP", ... }, "execution": { "entrypoint":"info" }, "outputs": [{ "name":"output_obj", "type":"list" }] } }

This approach decouples the optimization problem definition from implementation details, ensuring both reproducibility and maintainability across modeling languages and environments.

4. Model Lifecycle: API Usage and Workflow

A typical end-to-end workflow is as follows:

1. Model Authoring: Developer writes annotated optimization code.
2. Registration: User uploads annotated source code via POST /api/v1/models (Python SDK, web UI, or direct HTTP).
3. Discovery: Fetch model metadata and recipe using GET /api/v1/models/{model_id}.
4. Execution: Submit a new job with inputs/files using POST /api/v1/models/{model_id}/executions.
5. Monitoring: Poll execution status and logs through execution endpoints.
6. Result Retrieval: Retrieve solution output via GET /api/v1/models/{model_id}/executions/{exec_id}/result.

Annotated recipes can be overridden or extended post-registration, allowing for dynamic experimentation or adaptation to new problem instances. Both UI and client SDKs closely mirror API semantics.

5. Authentication, Authorization, and Error Protocols

M5ops secures endpoints using token-based authentication (e.g., JSON Web Tokens) passed via the HTTP Authorization: Bearer header. Tokens may bear roles such as reader, runner, or admin, and the backend enforces access controls at both the model and execution level.

Error handling follows conventional HTTP semantics with structured JSON error objects. Common status codes include:

• 401 Unauthorized: Invalid/missing token
• 403 Forbidden: Insufficient privilege
• 404 Not Found: Invalid model/execution identifier
• 400 Bad Request: Malformed payloads or schema violations
• 422 Unprocessable Entity: Semantically invalid input data
• 500 Internal Server Error: Backend or execution failures, accompanied by diagnostic fields

Error responses return a JSON block specifying an error code, message, and details (e.g., expected types for inputs).

6. Client Library Support and Code Examples

Native client SDKs abstract HTTP protocol details. The Python interface exposes an Interface object for model discovery, input binding, job submission, and result retrieval. Example usage includes:

from mos.interface import Interface iface = Interface(url="https://mos.example.com", token="eyJ…") model = iface.get_model_with_name("DCOPF Model") model.set_interface_object("feastol", 1e-3) with open("ieee14.m","rb") as f: model.set_interface_file(f, "case") run_info = model.run() sol = model.get_result(run_info["exec_id"])

JavaScript (Node.js) clients can program jobs with direct use of fetch, performing model listing, job submission, polling, and result extraction exclusively through HTTP calls.

7. Performance, Logging, and Scalability Considerations

The platform's stateless compute workers are horizontally scalable, permitting deployments with thousands of concurrent solves using queue-based scheduling (e.g., RabbitMQ, Redis streams). Each execution tracks fine-grained telemetry: scheduling, model assembly, solver runtime, and post-processing intervals. Centralized logging supports real-time inspection and post-hoc analysis.

Performance best practices include: maximizing model structure annotation for optimal data streaming, using file uploads for large arrays, pinning solver container images for reproducibility, and leveraging Redis caching for high-frequency solve environments. Sharding of models or clients is recommended at high scales to mitigate contention.

---

In sum, the M5ops API as part of MOS provides a model- and solver-agnostic layer for optimization model deployment, built on compositional annotations, robust REST endpoints, strong authentication and error handling protocols, comprehensive logging, and vertically/horizontally scalable compute mechanisms (Merrick et al., 2022). The methodology enables reproducible, production-grade optimization services accessible via standardized interfaces across programming environments.