API Reference: Detailed Guide

1. Overview

The Multi-Language Compiler Service provides a RESTful API endpoint for synchronous code execution. The API is designed to be simple, predictable, and easy to integrate. It accepts source code as a string, executes it in a secure, sandboxed environment on the server, and returns the execution output directly.

The API is stateless; no session information is retained between requests.

2. Authentication

The current version of the API is open and does not require any authentication tokens or API keys for access.

3. Primary Endpoint: POST /api/compile

This is the sole functional endpoint of the service. It is designed to receive, process, and execute a code snippet, returning the result in a single request-response cycle.

• HTTP Method: POST

• URL: /api/compile

• Content-Type: application/json

3.1. Request Body Parameters

The body of the POST request must be a JSON object containing the following key-value pairs:

Field	Type	Description	Constraints
code	String	The raw source code to be executed. The string can contain newlines (\n) and other special characters.	Required. Must be a valid string.
language	String	A case-sensitive string representing the programming language of the code field.	Required. Must be one of the enumerated values below.

Valid language Values:

• "custom": For the proprietary, custom-built interpreted language.

• "rust": For standard Rust code. The service uses rustc to compile and run the code.

• "python": For Python 3 code. The service uses the python3 interpreter.

• "c": For C code. The service uses gcc to compile and run the code.

3.2. Response Body Structure

The API will always respond with an HTTP 200 OK status code, regardless of whether the code execution was successful or resulted in an error. The success or failure state is communicated within the JSON response body itself.

The response object contains the following fields:

Field	Type	Description
result	String	null
error	String	null
execution_time_ms	Number	An integer representing the total time taken for the execution cycle on the server, measured in milliseconds. This is provided in both success and error responses.

4. Full End-to-End Examples

Here are several complete curl examples demonstrating how to use the API for different scenarios.

Example 1: Successful Python Execution

• Request:

curl -X POST 'http://<your-api-domain>/api/compile' \
--header 'Content-Type: application/json' \
--data-raw '{
    "code": "for i in range(5):\n    print(f\"Line {i+1}\")",
    "language": "python"
}'

Response

{
  "result": null,
  "error": "error: mismatched types\n --> main.rs:2:22\n  |\n2 |     let x: i32 = \"hello\";\n  |                  ^^^^^^^ expected `i32`, found `&str`\n\nerror: aborting due to previous error\n",
  "execution_time_ms": 76
}

Example 2: Rust Code with a Compilation Error

• Request:

curl -X POST 'http://<your-api-domain>/api/compile' \
--header 'Content-Type: application/json' \
--data-raw '{
    "code": "fn main() {\n    let x: i32 = \"hello\";\n    println!(\"{}\", x);\n}",
    "language": "rust"
}'

• Response:

{
  "result": null,
  "error": "error: mismatched types\n --> main.rs:2:22\n  |\n2 |     let x: i32 = \"hello\";\n  |                  ^^^^^^^ expected `i32`, found `&str`\n\nerror: aborting due to previous error\n",
  "execution_time_ms": 76
}

5. Error Handling and Best Practices

• Always Check the error Field: Since the HTTP status is always 200 OK, it is crucial for client applications to inspect the error field in the response body to determine if the code execution was successful. A non-null value in this field indicates failure.

• Timeout: While the API is designed to be fast, client applications should implement a reasonable request timeout (e.g., 10-15 seconds) to handle potential network issues or unexpectedly long-running code.

• Input Sanitization: While the backend executes code in a sandboxed environment, it is good practice for client applications to perform basic input validation or sanitization if the code originates from untrusted user input.