Sphere Engine Compilers API quickstart

This tutorial will show you how to start using the Compilers module API. For a detailed information about the available API methods go to the Compilers module API documentation.

Important: To successfully go through this tutorial you need to have a working Sphere Engine account with a dedicated API endpoint and API token. Register for a Sphere Engine account by filling in the sign-up form.

Step 1: Accessing the data

The Sphere Engine Compilers API is available at:

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

To call any API method, you need to be authenticated with an API token that you can generate in the token manager section of the Sphere Engine client panel.

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 using the curl command.

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-like 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
}

Note: To see what programming languages are supported by Compilers module and what are their unique IDs, please refer to the "Supported programming languages" article.

Step 3: Checking the result

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

To receive the result of the submission use the appropriate API method and submission identifier (here 42). The following example also uses the curl command:

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

Detailed information about the program will be returned. This example response reflects the structure of the submission result:

{
    "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
        }
    }
}