Getting started with Compilers API


This document shows how to quickly start using the Compilers module web service. Detailed information is available in the API documentation of the Compilers module

Step 1: Access data

The Sphere Engine Compilers web service is available at the following address:

https://<client_id>.compilers.sphere-engine.com/api/v4

For any call of an API method, the user is authenticated on the basis of the so-called access code that can be generated in the token manager.

You can check the correctness of the API authentication using the /test method:

https://<endpoint>/api/v4/test?access_token=<access_token>

Step 2: Creating a submission

The following example shows how to call the API method responsible for creating a new submission. The curl command was used.

curl -X POST -F "compilerId=1" -F "source=@prog.cpp" -F "input=input data" "https://<endpoint>/api/v4/submissions?access_token=<access_token>"

Alternatively, you can use any application or programming language that allows you to use HTTP queries. In the example above, we decided to use the curl command due to its simplicity and availability in UNIX systems.

The presented example sends a program written in C++ (i.e. compilerId = 1) that will be executed for the provided input data (i.e. entered in the input parameter).

In response, the unique identifier of the submission will be returned, for example:

{
  "id": 42
}

Step 3: Checking the result

After sending your submission, you should wait some time for it to be executed. While waiting for the execution, you can cyclically check its current status at intervals of a few seconds (learn more).

We receive the result of the submission by using the appropriate API method and submission identifier (42 in our example). The following example also uses the curl command:

curl "https://<endpoint>/api/v4/submissions/42?access_token=<access_token>"

Detailed information about the application will be returned. An example response has the following structure:

{
    "id": 42,
    "executing": false,
    "date": "2018-02-05 14:24:21 +00:00",
    "compiler": {
        "id": 1,
        "name": "C++",
        "version": {
            "id": 1,
            "name": "gcc 6.3"
        }
    },
    "result": {
        "status": {
            "code": 15,
            "name": "accepted"
        },
        "time": 0.4,
        "memory": 2048,
        "signal": 0,
        "streams": {
            "source": {
                "size": 189,
                "uri": "..."
            },
            "input": {
                "size": 56,
                "uri": "..."
            },
            "output": {
                "size": 11,
                "uri": "..."
            },
            "error": null,
            "cmpinfo": null
        }
    }
}