# API Reference: Detailed Guide

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:

```json
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

```json
{
  "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:

```concurnas
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:

```json
{
  "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.