Overview

Introduction

This document describes Sphere Engine Problems webservice. It is explained in here how the methods should be used and how to interpret data returned by them. All URLs referenced in the documentation have the base http://<endpoint>/api/v3. One of available access tokens is <access_token>.

Functionality

Sphere Engine Problems API allows you to:

  • create and modify problems, including:
    • description
    • general settings
    • test cases (model input, model output, judge)
    • master judge
  • submit a solution to the problem with one of more than 60 languages,
  • run the program with model input data on the server side,
  • download results of the execution (correctness status, execution time, consumed memory and much more technical details).

The webservice

All API URLs listed in this document are relative to the http://<endpoint>/api/v3/ link called an endpoint. For example, the /test API call is reachable at http://<endpoint>/api/v3/test?access_token=<access_token>.

The Sphere Engine Problems API is a RESTful API. This implies the following:

  • API calls should be made with HTTP requests (GET, POST, etc.),
  • successes are represented by the 2xx codes,
  • errors are represented by 4xx and 5xx codes,
  • error code from 4xx group represents client errors,
  • error code from 5xx group represents connection or server error.

Requests

Request data is passed to the API by posting parameters to the API endpoints. To communicate with API endpoint you can use any HTTP client/library. Each function takes at least one parameters - access_token. For every GET and DELETE request parameters have to be submitted in the query (i.e. url). For POST and PUT request you can send parameters in the two possible ways:

  • as a FORM (i.e. Content-Type: application/x-www-form-urlencoded)
  • as a JSON (i.e. Content-Type: application/json)

The documentation for each API call will contain more details on the parameters accepted by the call.

Responses

Each response has two components: Http Status Code and JSON-encoded message.

The RESTful API uses HTTP response code to communicate the success or error. Here is the general list of possible codes for Sphere Engine Compilers API.

Value Interpretation
200 success
201 success (for creation methods)
400 bad request (invalid parameters)
401 unauthorized access (missing or incorrect access token)
403 forbidden access (referring to foreign or secured content)
404 non existing content (submission or compiler)
5xx server side problem

Status code

A status parameter returned with submission details (i.e. using GET /submissions/:id API method) requires further explanation.

The status specifies stage of program's execution. We can devide the possible values of statuses into two separate groups.

Statuses from the first group are called transitional statuses. All of them are used during execution of the submission.

Value Description Meaning
<0 waiting for compilation the submission awaits execution in the queue
1,2 compilation the program is being compiled
3 running the program is being executed
4 compilation the judge is being compiled
5 running the judge is being executed
6 compilation the master judge is being compiled
7 running the master judge is being executed
8 testing the program is being tested

Statuses from the second group are called terminal or final statuses. One of these statuses is set at the end of execution of the submission.

Value Description Meaning
11 compilation error the program could not be executed due to compilation error
12 runtime error the program finished because of the runtime error, for example: division by zero, array index out of bounds, uncaught exception
13 time limit exceeded the program haven't stoped before the time limit
14 wrong answer program did not solve the problem
15 success submission is accepted as a correct solution
17 memory limit exceeded the program tried to use more memory than it is allowed to
20,21 internal error some other problem occurred; one of possible reasons is the error of the judge or master judge

It's a common practice to implement the following scenario for waiting for execution:

  1. submit source code,
  2. wait 5 seconds,
  3. retrieve submission details,
  4. (optional) present current status to the user,
  5. if the status <= 8 go back to step (2),
  6. (optional) present all execution details to the user.

The following diagram presents the idea of this algorithm (click to enlarge): Submission pooling ilustration

Client libraries

There are client libraries available for the following programming languages:

For every API method there is an example of calling this method from the client library.

POST /auth
To use Sphere Engine API, you will require an access token. You can generate it using this method or using token manager from the left hand side menu.

Parameters:

Name Type Located in Description
username* string formData API username
password* string formData API password

Response HTTP Code:

Code Description
200 success
401 invalid username or password
400 empty username or password

Success Response:

Field Type Description
access_token string access token
token_type string bearer
expires_in integer seconds to expire

Response example:

{
    "access_token": "<access_token>",
    "token_type": "Bearer",
    "expires_in": 2592000
}

Examples

$ cat request.json
{
    "username": "<username>", 
    "password": "<password>"
}

$ curl -X POST -H 'Content-Type: application/json' -d "`cat request.json`" 'http://<endpoint>/api/v3/auth'
var request = require('request');

var endpoint = '<endpoint>';

var authData = {
    username: '<username>',
    password: '<password>'
};

request({
    
    url: 'http://' + endpoint + '/api/v3/auth',
    method: 'POST',
    form: authData
}, function (error, response, body) {
    
    if (error) {
        console.log('Connection problem');
    }
    
    if (response) {
        if (response.statusCode === 200) {
            console.log(JSON.parse(response.body)); // auth data in JSON
        } else {
            if (response.statusCode === 401) {
                console.log('Invalid username or password');
            }
            if (response.statusCode === 400) {
                console.log('Empty username or password');
            }
        }
    }
});
GET /test?access_token=<access_token>
For testing purposes. This method should return testing string.

Parameters:

Name Type Located in Description
access_token* string query access token

Response HTTP Code:

Code Description
200 success
401 unauthorized access

Response example:

{
    "message": "You can use Sphere Engine Problems API."
}

Examples

curl -X GET -H 'Content-Type: application/json' 'http://<endpoint>/api/v3/test?access_token=<access_token>'
package problems;
/**
 * Example presents usage of the successful test() API method  
 */

import javax.ws.rs.NotAuthorizedException;

import com.SphereEngine.Api.ProblemsClientV3;
import com.google.gson.JsonObject;

public class testErrorHandling
{

	public static void main(String[] args) 
	{
		ProblemsClientV3 client = new ProblemsClientV3(
				"<access_token>", 
				"<endpoint>");
		
		try {
			JsonObject response = client.test();
		} catch (NotAuthorizedException e) {
			System.out.println("Invalid access token");
		}
	}	
}
<?php
/**
 * Example presents usage of the successful test() API method  
 */

use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;

// require library
require_once('../../autoload.php');

// define access parameters
$accessToken = '<access_token>';
$endpoint = '<endpoint>';

// initialization
$client = new ProblemsClientV3($accessToken, $endpoint);

// API usage
try {
    $response = $client->test();
} catch (SphereEngineResponseException $e) {
	if ($e->getCode() == 401) {
		echo 'Invalid access token';
	}
}
"""
Example presents usage of the successful test() API method
"""
from sphere_engine import ProblemsClientV3
from sphere_engine.exceptions import SphereEngineException

# define access parameters
accessToken = '<access_token>'
endpoint = '<endpoint>'

# initialization
client = ProblemsClientV3(accessToken, endpoint)

# API usage
try:
    response = client.test()
except SphereEngineException as e:
    if e.code == 401:
        print('Invalid access token')
var request = require('request');

var accessToken = '<access_token>';
var endpoint = '<endpoint>';

request({
    
    url: 'http://' + endpoint + '/api/v3/test?access_token=' + accessToken,
    method: 'GET'
}, function (error, response, body) {
	
    if (error) {
        console.log('Connection problem');
    }
    
    if (response) {
        if (response.statusCode === 200) {
            console.log(JSON.parse(response.body)); // test message in JSON
    } else {
        if (response.statusCode === 401) {
                console.log('Invalid access token');
            }
        }
    }
});
using System;
using System.IO;
using System.Net;
using System.Text;
using System.Collections.Generic;
using System.Collections.Specialized;

namespace csharpexamples
{
	public class test
	{
		public static void Main(string[] args)
		{
			string endpoint = "<endpoint>";
			string accessToken = "<access_token>";
				
			try {
				WebClient client = new WebClient();
					
				byte[] responseBytes = client.DownloadData("http://" + endpoint + "/api/v3/test?access_token=" + accessToken);
				string responseBody = Encoding.UTF8.GetString(responseBytes);
					
				Console.WriteLine(responseBody);

			} catch (WebException exception) {
				WebResponse response = exception.Response;
				HttpStatusCode statusCode = (((HttpWebResponse) response).StatusCode);

				if (statusCode == HttpStatusCode.Unauthorized) {
					Console.WriteLine("Invalid access token");
				}
					
				response.Close();
			}
		}
	}
}

GET /compilers?access_token=<access_token>
Returns a list of supported compilers.

Parameters:

Name Type Located in Description
access_token* string query access token

Response HTTP Code:

Code Description
200 success
401 unauthorized access

Success Response:

Field Type Description
items[].id integer compiler id
items[].name string compiler name
items[].ver string compiler version
items[].short string short name
items[].ace string syntax highlighting identifier for Ace
items[].geshi string syntax highlighting identifier for Geshi
items[].pygments string syntax highlighting identifier for Pygments
items[].highlighting string syntax highlighting identifier for Highlighting
items[].rouge string syntax highlighting identifier for Rouge
items[].codemirror string syntax highlighting identifier for CodeMirror

Response example:

{
    "items": [
        {
            "id": 1,
            "name": "C++",
            "ver": "gcc 6.3",
            "short": "CPP",
            "ace": "c_cpp", 
            "geshi": "cpp",
            "pygments": "cpp",
            "highlights": "c",
            "rouge": "cpp",
            "codemirror": "clike"
        },
        {
            "id": 116,
            "name": "Python 3",
            "ver": "3.5",
            "short": "PYTHON3",
            "ace": "python",
            "geshi": "python",
            "pygments": "python",
            "highlights": "python",
            "rouge": "python",
            "codemirror": "python"
        }
    ]
}

Examples

curl -X GET -H 'Content-Type: application/json' 'http://<endpoint>/api/v3/compilers?access_token=<access_token>'
package problems;
/**
 * Example presents usage of the successful getCompilers() API method  
 */

import javax.ws.rs.NotAuthorizedException;

import com.SphereEngine.Api.ProblemsClientV3;
import com.google.gson.JsonObject;

public class getCompilersErrorHandling
{

	public static void main(String[] args) 
	{
		ProblemsClientV3 client = new ProblemsClientV3(
				"<access_token>", 
				"<endpoint>");
		
		try {
			JsonObject response = client.getCompilers();
		} catch (NotAuthorizedException e) {
			System.out.println("Invalid access token");
		}
	}	
}
<?php
/**
 * Example presents usage of the successful getCompilers() API method  
 */

use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;

// require library
require_once('../../autoload.php');

// define access parameters
$accessToken = '<access_token>';
$endpoint = '<endpoint>';

// initialization
$client = new ProblemsClientV3($accessToken, $endpoint);

// API usage
try {
    $response = $client->getCompilers();
} catch (SphereEngineResponseException $e) {
	if ($e->getCode() == 401) {
		echo 'Invalid access token';
	}
}
"""
Example presents usage of the successful compilers() API method
"""
from sphere_engine import ProblemsClientV3
from sphere_engine.exceptions import SphereEngineException

# define access parameters
accessToken = '<access_token>'
endpoint = '<endpoint>'

# initialization
client = ProblemsClientV3(accessToken, endpoint)

# API usage
try:
    response = client.compilers()
except SphereEngineException as e:
    if e.code == 401:
        print('Invalid access token')
var request = require('request');

var accessToken = '<access_token>';
var endpoint = '<endpoint>';

request({
    
    url: 'http://' + endpoint + '/api/v3/compilers?access_token=' + accessToken,
    method: 'GET'
}, function (error, response, body) {
	
    if (error) {
        console.log('Connection problem');
    }
    
    if (response) {
        if (response.statusCode === 200) {
            console.log(JSON.parse(response.body)); // list of compilers in JSON
        } else {
            if (response.statusCode === 401) {
                console.log('Invalid access token');
            }
        }
    }
});
using System;
using System.IO;
using System.Net;
using System.Text;
using System.Collections.Generic;
using System.Collections.Specialized;

namespace csharpexamples
{
	public class getCompilers
	{
		public static void Main(string[] args)
		{
			string endpoint = "<endpoint>";
			string accessToken = "<access_token>";

			try {
				WebClient client = new WebClient();

				byte[] responseBytes = client.DownloadData("http://" + endpoint + "/api/v3/compilers?access_token=" + accessToken);
				string responseBody = Encoding.UTF8.GetString(responseBytes);

				Console.WriteLine(responseBody);

			} catch (WebException exception) {
				WebResponse response = exception.Response;
				HttpStatusCode statusCode = (((HttpWebResponse) response).StatusCode);

				if (statusCode == HttpStatusCode.Unauthorized) {
					Console.WriteLine("Invalid access token");
				}

				response.Close();
			}
		}
	}
}

GET /submissions/:id?access_token=<access_token>
Returns information about a submission.

Parameters:

Name Type Located in Description
access_token* string query access token
id* string path submission id

Response HTTP Code:

Code Description
200 success
401 unauthorized access
403 access denied
404 submission not found

Success Response:

Field Type Description
id integer submission id
date string submission date
source string source code
compiler.id integer compiler id
compiler.name string compiler name
compiler.ver string compiler version
problem.code string problem code
problem.name string problem name
problem.uri string problem more details
result.status string submission status
result.status_code integer submission status code
result.signal integer exit signal
result.time float execution time in seconds
result.memory integer consumed memory in kilobytes
result.score float submission final score
result.runtime_info.psinfo string psinfo data
result.runtime_info.stderr string stderr data, truncated to 1000 characters
result.runtime_info.cmperr string cmperr data
result.runtime_info.stdout string stdout data, truncated to 5000 characters; please note that this field should serve debugging purposes only, it shouldn't be used to assess submission correctness (use proper judges and the result.status field for that)
result.testcases[].number integer test case number
result.testcases[].status string test case status
result.testcases[].status_code integer test case status code
result.testcases[].signal integer test case exit signal
result.testcases[].time float test case execution time in seconds
result.testcases[].memory integer test case consumed memory in kilobytes
result.testcases[].score float test case score

Response example:

{
    "id": 42,
    "date": "2017-02-24 10:02:26 +00:00",
    "source": "source code",
    "compiler": {
        "id": 1,
        "name": "C++",
        "ver": "gcc 6.3"
    },
    "problem": {
        "code": "EXPRBL", 
        "name": "Example Problem", 
        "uri": "http://<endpoint>/api/v3/problems/EXPRBL?access_token=<access_token>"
    },
    "result": {
        "status": "accepted",
        "status_code": 15,
        "signal": 0, 
        "time": 1.24,
        "memory": 2048,
        "score": 100,
        "runtime_info": {
            "psinfo": "",
            "stderr": "",
            "cmperr": "",
            "stdout": ""
        },
        "testcases": [
            {
                "number": 0,
                "status": "accepted",
                "status_code": 15,
                "signal": 0, 
                "time": 1.24,
                "memory": 2048,
                "score": 100
            }
        ]
    }
}

Examples

curl -X GET -H 'Content-Type: application/json' 'http://<endpoint>/api/v3/submissions/:id?access_token=<access_token>'
package problems.submissions;
/**
 * Example presents error handling for getSubmission() API method  
 */

import javax.ws.rs.NotAuthorizedException;
import javax.ws.rs.NotFoundException;

import com.SphereEngine.Api.ProblemsClientV3;
import com.google.gson.JsonObject;

public class getSubmissionErrorHandling
{

	public static void main(String[] args) 
	{
		ProblemsClientV3 client = new ProblemsClientV3(
				"<access_token>", 
				"<endpoint>");
		
		try {
			JsonObject response = client.getSubmission(2016);
		} catch (NotAuthorizedException e) {
			System.out.println("Invalid access token");
		} catch (NotFoundException e) {
			System.out.println("Submission does not exist");
		}
	}	
}
<?php
/**
 * Example presents error handling for getSubmission() API method
 */

use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;

// require library
require_once('../../../autoload.php');

// define access parameters
$accessToken = '<access_token>';
$endpoint = '<endpoint>';

// initialization
$client = new ProblemsClientV3($accessToken, $endpoint);

// API usage
try {
	$response = $client->getSubmission(2016);
} catch (SphereEngineResponseException $e) {
	if ($e->getCode() == 401) {
		echo 'Invalid access token';
	} elseif ($e->getCode() == 404) {
		echo 'Submission does not exist';
	}
}
"""
Example presents error handling for submissions.get() API method
"""
from sphere_engine import ProblemsClientV3
from sphere_engine.exceptions import SphereEngineException

# define access parameters
accessToken = '<access_token>'
endpoint = '<endpoint>'

# initialization
client = ProblemsClientV3(accessToken, endpoint)

# API usage
try:
    response = client.submissions.get(2016)
except SphereEngineException as e:
    if e.code == 401:
        print('Invalid access token')
    elif e.code == 404:
        print('Submission does not exist')
var request = require('request');

var accessToken = '<access_token>';
var endpoint = '<endpoint>';

var submissionId = 2016;

request({
    
    url: 'http://' + endpoint + '/api/v3/submissions/' + submissionId + '?access_token=' + accessToken,
    method: 'GET'
}, function (error, response, body) {
    
    if (error) {
        console.log('Connection problem');
    }
    
    if (response) {
        if (response.statusCode === 200) {
            console.log(JSON.parse(response.body)); // submission data in JSON
        } else {
            if (response.statusCode === 401) {
                console.log('Invalid access token');
            }
            if (response.statusCode === 403) {
                console.log('Access denied');
            }
            if (response.statusCode === 404) {
                console.log('Submision not found');
            }
        }
    }
});
using System;
using System.IO;
using System.Net;
using System.Text;
using System.Collections.Generic;
using System.Collections.Specialized;

namespace csharpexamples
{
	public class getSubmission
	{
		public static void Main(string[] args)
		{
			string endpoint = "<endpoint>";
			string accessToken = "<access_token>";

			int submissionId = 2016;

			try {
				WebClient client = new WebClient();

				byte[] responseBytes = client.DownloadData("http://" + endpoint + "/api/v3/submissions/" + submissionId + "?access_token=" + accessToken);
				string responseBody = Encoding.UTF8.GetString(responseBytes);

				Console.WriteLine(responseBody);

			} catch (WebException exception) {
				WebResponse response = exception.Response;
				HttpStatusCode statusCode = (((HttpWebResponse) response).StatusCode);

				if (statusCode == HttpStatusCode.Unauthorized) {
					Console.WriteLine("Invalid access token");
				} else if (statusCode == HttpStatusCode.Forbidden) {
					Console.WriteLine("Access denied");
				} else if (statusCode == HttpStatusCode.NotFound) {
					Console.WriteLine("Submission not found");
				}

				response.Close();
			}
		}
	}
}

POST /submissions?access_token=<access_token>
Create a new submission

Parameters:

Name Type Located in Description
access_token* string query access token
problemCode* string formData problem code
source* string formData source code
compilerId* integer formData compiler id
userId integer formData user id, default: account owner user

Response HTTP Code:

Code Description
201 success
401 unauthorized access
403 compiler not available
400 empty source code
404 problem not found | compiler not found | user not found

Success Response:

Field Type Description
id integer id of created submission

Response example:

{
    "id": 42
}

Examples

$ cat request.json
{
    "problemCode": "SETEST", 
    "compilerId": 1, 
    "source": "<source code>"
}

$ curl -X POST -H 'Content-Type: application/json' -d "`cat request.json`" 'http://<endpoint>/api/v3/submissions?access_token=<access_token>'
package problems.submissions;
/**
 * Example presents error handling for createSubmission() API method
*/

import javax.ws.rs.BadRequestException;
import javax.ws.rs.NotAuthorizedException;
import javax.ws.rs.NotFoundException;

import com.SphereEngine.Api.ProblemsClientV3;
import com.google.gson.JsonObject;

public class createSubmissionErrorHandling
{

	public static void main(String[] args) 
	{
		ProblemsClientV3 client = new ProblemsClientV3(
				"<access_token>", 
				"<endpoint>");
		
		String problemCode = "TEST";
		String source = "<source code>";
		Integer nonexistingCompiler = 99999;
		
		try {
			JsonObject response = client.createSubmission(problemCode, source, nonexistingCompiler);
		} catch (NotAuthorizedException e) {
			System.out.println("Invalid access token");
		} catch (NotFoundException e) {
			// aggregates three possible reasons of 404 error
			// non existing problem, compiler or user
			System.out.println("Non existing resource (problem, compiler or user), details available in the message: " + e.getMessage());
		} catch (BadRequestException e) {
			System.out.println("Empty source code");
		}
	}	
}
<?php
/**
 * Example presents error handling for createSubmission() API method
*/

use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;

// require library
require_once('../../../autoload.php');

// define access parameters
$accessToken = '<access_token>';
$endpoint = '<endpoint>';

// initialization
$client = new ProblemsClientV3($accessToken, $endpoint);

// API usage
$problemCode = 'TEST';
$source = '<source code>';
$nonexistingCompiler = 99999;

try {
	$response = $client->createSubmission($problemCode, $source, $nonexistingCompiler);
	// response['id'] stores the ID of the created submission
} catch (SphereEngineResponseException $e) {
	if ($e->getCode() == 401) {
		echo 'Invalid access token';
	} elseif ($e->getCode() == 404) {
		// aggregates three possible reasons of 404 error
		// non existing problem, compiler or user
		echo 'Non existing resource (problem, compiler or user), details available in the message: ' . $e->getMessage();
	} elseif ($e->getCode() == 400) {
		echo 'Empty source code';
	}
}
"""
Example presents error handling for submissions.create() API method
"""
from sphere_engine import ProblemsClientV3
from sphere_engine.exceptions import SphereEngineException

# define access parameters
accessToken = '<access_token>'
endpoint = '<endpoint>'

# initialization
client = ProblemsClientV3(accessToken, endpoint)

# API usage
problemCode = 'TEST'
source = '<source code>'
nonexistingCompiler = 99999;

try:
    response = client.submissions.create(problemCode, source, nonexistingCompiler)
    # response['id'] stores the ID of the created submission
except SphereEngineException as e:
    if e.code == 401:
        print('Invalid access token')
    elif e.code == 404:
        # aggregates three possible reasons of 404 error
        # non existing problem, compiler or user
        print('Non existing resource (problem, compiler or user), details available in the message: ' + str(e))
    elif e.code == 400:
        print('Empty source code')
var request = require('request');

var accessToken = '<access_token>';
var endpoint = '<endpoint>';

var submissionData = {
    problemCode: 'EXAMPLE',
    compilerId: 11,
    source: '<source_code>'
};

request({
    
    url: 'http://' + endpoint + '/api/v3/submissions?access_token=' + accessToken,
    method: 'POST',
    form: submissionData
}, function (error, response, body) {
    
    if (error) {
        console.log('Connection problem');
    }
    
    if (response) {
        if (response.statusCode === 201) {
            console.log(JSON.parse(response.body)); // submission data in JSON
        } else {
            if (response.statusCode === 401) {
                console.log('Invalid access token');
            }
            if (response.statusCode === 400) {
                console.log('Empty source code');
            }
            if (response.statusCode === 404) {
                console.log('Problem, compiler or user does not exist');
            }
        }
    }
});
using System;
using System.IO;
using System.Net;
using System.Text;
using System.Collections.Generic;
using System.Collections.Specialized;

namespace csharpexamples
{
	public class createSubmission
	{
		public static void Main(string[] args)
		{
			string endpoint = "<endpoint>";
			string accessToken = "<access_token>";

			try {
				WebClient client = new WebClient ();

				NameValueCollection formData = new NameValueCollection ();
				formData.Add("problemCode", "EXAMPLE");
				formData.Add("source", "<source_code>");
				formData.Add("compilerId", "1111");

				byte[] responseBytes = client.UploadValues ("http://" + endpoint + "/api/v3/submissions?access_token=" + accessToken, "POST", formData);
				string responseBody = Encoding.UTF8.GetString(responseBytes);

				Console.WriteLine(responseBody);

			} catch (WebException exception) {
				WebResponse response = exception.Response;
				HttpStatusCode statusCode = (((HttpWebResponse)response).StatusCode);

				if (statusCode == HttpStatusCode.Unauthorized) {
					Console.WriteLine("Invalid access token");
				}
				if (statusCode == HttpStatusCode.BadRequest) {
					Console.WriteLine("Empty source code");
				}
				if (statusCode == HttpStatusCode.Forbidden) {
					Console.WriteLine("Compiler not available");
				}
				if (statusCode == HttpStatusCode.NotFound) {
					Console.WriteLine("Problem, compiler or user not found");
				}

				response.Close();
			}
		}
	}
}

GET /submissions?access_token=<access_token>
Returns information about submissions. Results are sorted ascending by id.

Parameters:

Name Type Located in Description
access_token* string query access token
ids* string query ids of submissions separated by comma, maximum 20 ids

Response HTTP Code:

Code Description
200 success
401 unauthorized access

Success Response:

Field Type Description
items[].id integer submission id
items[].date string submission date
items[].compiler.id integer compiler id
items[].compiler.name string compiler name
items[].compiler.ver string compiler version
items[].problem.code string problem code
items[].problem.name string problem name
items[].problem.uri string problem more details
items[].result.status string submission status
items[].result.status_code integer submission status code
items[].result.signal integer exit signal
items[].result.time float execution time in seconds
items[].result.memory integer consumed memory
items[].result.score float submission final score
items[].result.testcases[].number integer test case number
items[].result.testcases[].status string test case status
items[].result.testcases[].status_code integer test case status code
items[].result.testcases[].signal integer test case exit signal
items[].result.testcases[].time float test case execution time in seconds
items[].result.testcases[].memory integer test case consumed memory in kilobytes
items[].result.testcases[].score float test case score

Response example:

{
    "items": [
        {
            "id": 42,
            "date": "2017-02-24 10:02:26 +00:00",
            "compiler": {
                "id": 1,
                "name": "C++",
                "ver": "gcc 6.3"
            },
            "problem": {
                "code": "EXPRBL",
                "name": "Example Problem",
                "uri": "http://<endpoint>/api/v3/problems/EXPRBL?access_token=<access_token>"
            },
            "result": {
                "status": "accepted",
                "status_code": 15,
                "signal": 0,
                "time": 1.24,
                "memory": 2048,
                "score": 100,
                "testcases": [
                    {
                        "number": 0,
                        "status": "accepted",
                        "status_code": 15,
                        "signal": 0,
                        "time": 1.24,
                        "memory": 2048,
                        "score": 100
                    }
                ]
            }
        }
    ]
}

Examples

curl -X GET -H 'Content-Type: application/json' 'http://<endpoint>/api/v3/submissions?ids=:ids&access_token=<access_token>'
package problems.submissions;
/**
 * Example presents error handling for getSubmissions() API method  
 */

import javax.ws.rs.NotAuthorizedException;

import com.SphereEngine.Api.ProblemsClientV3;
import com.google.gson.JsonObject;

public class getSubmissionsErrorHandling
{

	public static void main(String[] args) 
	{
		ProblemsClientV3 client = new ProblemsClientV3(
				"<access_token>", 
				"<endpoint>");
		
		try {
			Integer[] ids = new Integer[2];
			ids[0] = 2017;
			ids[1] = 2018;

			JsonObject response = client.getSubmissions(ids);
		} catch (NotAuthorizedException e) {
			System.out.println("Invalid access token");
		}
	}	
}
<?php
/**
 * Example presents error handling for getSubmissions() API method
*/

use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;

// require library
require_once('../../../autoload.php');

// define access parameters
$accessToken = '<access_token>';
$endpoint = '<endpoint>';

// initialization
$client = new ProblemsClientV3($accessToken, $endpoint);

// API usage
try {
	$response = $client->getSubmissions(array(2017, 2018));
} catch (SphereEngineResponseException $e) {
	if ($e->getCode() == 401) {
		echo 'Invalid access token';
	}
}
"""
Example presents error handling for submissions.getMulti() API method
"""
from sphere_engine import ProblemsClientV3
from sphere_engine.exceptions import SphereEngineException

# define access parameters
accessToken = '<access_token>'
endpoint = '<endpoint>'

# initialization
client = ProblemsClientV3(accessToken, endpoint)

# API usage
try:
    response = client.submissions.getMulti([2017, 2018])
except SphereEngineException as e:
    if e.code == 401:
        print('Invalid access token')
var request = require('request');

var accessToken = '<access_token>';
var endpoint = '<endpoint>';

var submissionsIds = [2016, 2017];

request({
    
    url: 'http://' + endpoint + '/api/v3/submissions?ids=' + submissionsIds.join() + '&access_token=' + accessToken,
    method: 'GET'
}, function (error, response, body) {
    
    if (error) {
        console.log('Connection problem');
    }
    
    if (response) {
        if (response.statusCode === 200) {
            console.log(JSON.parse(response.body)); // list of submissions in JSON
        } else {
            if (response.statusCode === 401) {
                console.log('Invalid access token');
            }
        }
    }
});
GET /problems?access_token=<access_token>
Returns the list of problems of the quantity given by limit parameter starting from the offset parameter.

Parameters:

Name Type Located in Description
access_token* string query access token
limit integer query limit of problems to get, default: 10, max: 100
offset integer query offset, default: 0
shortBody boolean query whether shortened body should be returned, default: false

Response HTTP Code:

Code Description
200 success
401 unauthorized access

Success Response:

Field Type Description
items[].code string problem code
items[].name string problem name
items[].shortBody string shortened problem description (present only if shortBody = true)
items[].lastModifiedBody integer timestamp of the last modification date of problem name or problem description
items[].lastModifiedSettings integer timestamp of the last modification date of problem settings (type, interactivity, master judge, active test cases, new test cases, updated test cases)
items[].actions.edit boolean true if you can edit this problem
items[].actions.clone boolean true if you can clone this problem
items[].uri string problem details
paging.limit integer items per page
paging.offset integer first item
paging.total integer total number of items
paging.pages integer total number of pages for the current limit
paging.next string next page, link or empty if no page
paging.prev string previous page, link or empty if no page

Response example:

{
    "items": [
        {
            "code": "EXPRBL",
            "name": "Example Problem",
            "lastModifiedBody": 1486478234,
            "lastModifiedSettings": 1487929707,
            "actions": {
                "edit":true,
                "clone":true
            },
            "uri": "http://<endpoint>/api/v3/problems/TEST?access_token=<access_token>"
        },
        {
            "code": "ANOPRBL",
            "name": "Another problem",
            "lastModifiedBody": 1486491532,
            "lastModifiedSettings": 1486496511,
            "actions": {
                "edit":true,
                "clone":true
            },
            "uri": "http://<endpoint>/api/v3/problems/TEST?access_token=<access_token>"
        }
    ],
    "paging": {
        "limit": 2,
        "offset": 4,
        "total": 7,
        "pages": 4,
        "prev": "http://<endpoint>/api/v3/problems?offset=2&access_token=<access_token>",
        "next": "http://<endpoint>/api/v3/problems?offset=6&access_token=<access_token>"
    }
}

Examples

curl -X GET -H 'Content-Type: application/json' 'http://<endpoint>/api/v3/problems?access_token=<access_token>'
package problems.problems;
/**
 * Example presents usage of the successful getProblems() API method  
 */

import com.SphereEngine.Api.ProblemsClientV3;
import com.google.gson.JsonObject;

public class getProblems 
{

	public static void main(String[] args) 
	{
		ProblemsClientV3 client = new ProblemsClientV3(
				"<access_token>", 
				"<endpoint>");
		
		JsonObject response = client.getProblems();
	}	
}
<?php
/**
 * Example presents usage of the successful getProblems() API method  
 */

use SphereEngine\Api\ProblemsClientV3;

// require library
require_once('../../../autoload.php');

// define access parameters
$accessToken = '<access_token>';
$endpoint = '<endpoint>';

// initialization
$client = new ProblemsClientV3($accessToken, $endpoint);

// API usage
$response = $client->getProblems();
"""
Example presents usage of the successful problems.all() API method
"""
from sphere_engine import ProblemsClientV3

# define access parameters
accessToken = '<access_token>'
endpoint = '<endpoint>'

# initialization
client = ProblemsClientV3(accessToken, endpoint)

# API usage
response = client.problems.all()
var request = require('request');

var accessToken = '<access_token>';
var endpoint = '<endpoint>';

request({
    
    url: 'http://' + endpoint + '/api/v3/problems?access_token=' + accessToken,
    method: 'GET'
}, function (error, response, body) {
    
    if (error) {
        console.log('Connection problem');
    }
    
    if (response) { 
        if (response.statusCode === 200) {
            console.log(JSON.parse(response.body)); // list of problems in JSON
        } else {
            if (response.statusCode === 401) {
                console.log('Invalid access token');
            }
        }
    }
});
POST /problems?access_token=<access_token>
Creates a new problem

Parameters:

Name Type Located in Description
access_token* string query access token
code* string formData problem code
name* string formData problem name
body string formData problem body
type string formData problem type, enum: binary|min|max, default: binary
interactive boolean formData interactive problem flag, default: 0
masterjudgeId integer formData master judge id, default: 1001 (i.e. Score is % of correctly solved test cases)

Response HTTP Code:

Code Description
201 success
401 unauthorized access
403 access to master judge forbidden
400 empty problem code | empty problem name | problem code is not unique | problem code is invalid
404 master judge not found

Success Response:

Field Type Description
code string code of created problem

Response example:

{
    "code": "PROBLEMCODE"
}

Examples

$ cat request.json
{
    "code": "<PROBLEMCODE>", 
    "name": "Name"
}

$ curl -X POST -H 'Content-Type: application/json' -d "`cat request.json`" 'http://<endpoint>/api/v3/problems?access_token=<access_token>'
package problems.problems;
/**
 * Example presents error handling for createProblem() API method  
 */

import javax.ws.rs.BadRequestException;
import javax.ws.rs.NotAuthorizedException;
import javax.ws.rs.NotFoundException;

import com.SphereEngine.Api.ProblemsClientV3;
import com.google.gson.JsonObject;

public class createProblemErrorHandling 
{

	public static void main(String[] args) 
	{
		ProblemsClientV3 client = new ProblemsClientV3(
				"<access_token>", 
				"<endpoint>");
		
		String code = "EXAMPLE";
		String name = "Example problem"; 
		
		try {
			JsonObject response = client.createProblem(code, name);
			// response.get("id") stores the ID of the created problem
		} catch (NotAuthorizedException e) {
			System.out.println("Invalid access token");
		} catch (NotFoundException e) {
			System.out.println("Masterjudge does not exist");
		} catch (BadRequestException e) {
			// aggregates four possible reasons of 400 error
			// empty problem code, empty problem name, not unique problem code, invalid problem code
			System.out.println("Bad request (empty problem code, empty problem name, not unique problem code, invalid problem code), details available in the message: " + e.getMessage());
		}
	}	
}
<?php
/**
 * Example presents error handling for createProblem() API method  
*/

use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;

// require library
require_once('../../../autoload.php');

// define access parameters
$accessToken = '<access_token>';
$endpoint = '<endpoint>';

// initialization
$client = new ProblemsClientV3($accessToken, $endpoint);

// API usage
$code = "EXAMPLE";
$name = "Example problem"; 

try {
	$response = $client->createProblem($code, $name);
	// response['id'] stores the ID of the created problem
} catch (SphereEngineResponseException $e) {
	if ($e->getCode() == 401) {
		echo 'Invalid access token';
	} elseif ($e->getCode() == 400) {
		// aggregates four possible reasons of 400 error
		// empty problem code, empty problem name, not unique problem code, invalid problem code
		echo 'Bad request (empty problem code, empty problem name, not unique problem code, invalid problem code), details available in the message: ' . $e->getMessage();
	} elseif ($e->getCode() == 404) {
		echo 'Masterjudge does not exist';
	}
}
"""
Example presents error handling for problems.create() API method
"""
from sphere_engine import ProblemsClientV3
from sphere_engine.exceptions import SphereEngineException

# define access parameters
accessToken = '<access_token>'
endpoint = '<endpoint>'

# initialization
client = ProblemsClientV3(accessToken, endpoint)

# API usage
code = 'EXAMPLE'
name = 'Example problem'

try:
    response = client.problems.create(code, name)
    # response['id'] stores the ID of the created problem
except SphereEngineException as e:
    if e.code == 401:
        print('Invalid access token')
    elif e.code == 400:
        # aggregates four possible reasons of 400 error
        # empty problem code, empty problem name, not unique problem code, invalid problem code
        print('Bad request (empty problem code, empty problem name, not unique problem code, invalid problem code), details available in the message: ' + str(e))
    elif e.code == 404:
        print('Masterjudge does not exist')
var request = require('request');

var accessToken = '<access_token>';
var endpoint = '<endpoint>';

var problemData = {
    name: 'Example',
    code: 'EXAMPLE'
};

request({
    
    url: 'http://' + endpoint + '/api/v3/problems?access_token=' + accessToken,
    method: 'POST',
    form: problemData
}, function (error, response, body) {
    
    if (error) {
        console.log('Connection problem');
    }
    
    if (response) {
        if (response.statusCode === 201) {
            console.log(JSON.parse(response.body)); // problem data in JSON
        } else {
            if (response.statusCode === 401) {
                console.log('Invalid access token');
            }
            if (response.statusCode === 400) {
                console.log('Empty name, empty code, not unique code or invalid code');
            }
            if (response.statusCode === 404) {
                console.log('Masterjudge does not exist');
            }
        }
    }
});
GET /problems/:code?access_token=<access_token>
Retrieves an existing problem

Parameters:

Name Type Located in Description
access_token* string query access token
code* string path problem code
shortBody boolean query whether shortened body should be returned, default: false

Response HTTP Code:

Code Description
200 success
401 unauthorized access
403 access denied
404 problem not found

Success Response:

Field Type Description
code string problem code
name string problem name
body string problem description
type string type of the problem, binary|min|max
interactive boolean interactive problem flag
shortBody string shortened problem description (present only if shortBody = true)
masterjudge.id integer master judge id
masterjudge.name string master judge name
masterjudge.uri string master judge uri
testcases[].number integer test case number
testcases[].active boolean if test is active
lastModifiedBody integer timestamp of the last modification date of problem name or problem description
lastModifiedSettings integer timestamp of the last modification date of problem settings (type, interactivity, master judge, active test cases, new test cases, updated test cases)

Response example:

{
    "code": "EXPRBL",
    "name": "Example Problem",
    "body": "problem description",
    "type": "binary",
    "interactive": 0,
    "masterjudge": {
        "id": 1001,
        "name": "Score is % of correctly solved sets",
        "uri": "http://<endpoint>/judges/1001?access_token=<access_token>"
    },
    "testcases": [
        {
            "number": 0,
            "active": true
        },
        {
            "number": 1,
            "active": false
        }
    ],
    "lastModifiedBody": 1486478234,
    "lastModifiedSettings": 1487929707
}

Examples

curl -X GET -H 'Content-Type: application/json' 'http://<endpoint>/api/v3/problems/:code?access_token=<access_token>'
package problems.problems;
/**
 * Example presents error handling for getProblem() API method   
 */

import javax.ws.rs.ForbiddenException;
import javax.ws.rs.NotAuthorizedException;
import javax.ws.rs.NotFoundException;

import com.SphereEngine.Api.ProblemsClientV3;
import com.google.gson.JsonObject;

public class getProblemErrorHandling 
{

	public static void main(String[] args) 
	{
		ProblemsClientV3 client = new ProblemsClientV3(
				"<access_token>", 
				"<endpoint>");
		
		String problemCode = "NONEXISTING_CODE";
		
		try {
			JsonObject response = client.getProblem(problemCode);
		} catch (NotAuthorizedException e) {
			System.out.println("Invalid access token");
		} catch (NotFoundException e) {
			System.out.println("Problem does not exist");
		}
	}	
}
<?php
/**
 * Example presents error handling for getProblem() API method    
 */

use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;

// require library
require_once('../../../autoload.php');

// define access parameters
$accessToken = '<access_token>';
$endpoint = '<endpoint>';

// initialization
$client = new ProblemsClientV3($accessToken, $endpoint);

// API usage
$problemCode = 'NONEXISTING_CODE';
try {
	$response = $client->getProblem($problemCode);
} catch (SphereEngineResponseException $e) {
	if ($e->getCode() == 401) {
		echo 'Invalid access token';
	} elseif ($e->getCode() == 404) {
		echo 'Problem does not exist';
	}
}
"""
Example presents error handling for problems.get() API method
"""
from sphere_engine import ProblemsClientV3
from sphere_engine.exceptions import SphereEngineException

# define access parameters
accessToken = '<access_token>'
endpoint = '<endpoint>'

# initialization
client = ProblemsClientV3(accessToken, endpoint)

# API usage
problemCode = 'NONEXISTING_CODE'

try:
    response = client.problems.get(problemCode)
except SphereEngineException as e:
    if e.code == 401:
        print('Invalid access token')
    elif e.code == 404:
        print('Problem does not exist')
var request = require('request');

var accessToken = '<access_token>';
var endpoint = '<endpoint>';

var problemCode = 'EXAMPLE';

request({
    
    url: 'http://' + endpoint + '/api/v3/problems/' + problemCode + '?access_token=' + accessToken,
    method: 'GET'
}, function (error, response, body) {
    
    if (error) {
        console.log('Connection problem');
    }
    
    if (response) {
        if (response.statusCode === 200) {
            console.log(JSON.parse(response.body)); // problem data in JSON
        } else {
            if (response.statusCode === 401) {
                console.log('Invalid access token');
            }
            if (response.statusCode === 403) {
                console.log('Access denied');
            }
            if (response.statusCode === 404) {
                console.log('Problem not found');
            }
        }
    }
});
PUT /problems/:code?access_token=<access_token>
Updates an existing problem

Parameters:

Name Type Located in Description
access_token* string query access token
code* string path problem code
name string formData problem name
body string formData problem body
type string formData problem type, enum: binary|min|max, default: binary
interactive boolean formData interactive problem flag
masterjudgeId integer formData master judge id
activeTestcases string formData list of active test cases ids (comma separated)

Response HTTP Code:

Code Description
200 success
401 unauthorized access
403 access denied | access to master judge forbidden
400 problem code is empty | problem name is empty
404 problem not found | master judge not found

Response example:

{}

Examples

$ cat request.json
{
    "name": "<new_name>"
}

curl -X PUT -H 'Content-Type: application/json' -d "`cat request.json`" 'http://<endpoint>/api/v3/problems/:code?access_token=<access_token>'
package problems.problems;
/**
 * Example presents error handling for updateProblem() API method  
 */

import javax.ws.rs.BadRequestException;
import javax.ws.rs.ForbiddenException;
import javax.ws.rs.NotAuthorizedException;
import javax.ws.rs.NotFoundException;

import com.SphereEngine.Api.ProblemsClientV3;
import com.google.gson.JsonObject;

public class updateProblemErrorHandling 
{

	public static void main(String[] args) 
	{
		ProblemsClientV3 client = new ProblemsClientV3(
				"<access_token>", 
				"<endpoint>");
		
		String problemCode = "NONEXISTING_CODE";
		String newProblemName = "New example problem name";
		
		try {
			JsonObject response = client.updateProblem(problemCode, newProblemName);
		} catch (NotAuthorizedException e) {
			System.out.println("Invalid access token");
		} catch (ForbiddenException e) {
			System.out.println("Access to the problem is forbidden");
		} catch (NotFoundException e) {
			// aggregates two possible reasons of 404 error
			// non existing problem or masterjudge
			System.out.println("Non existing resource (problem, masterjudge), details available in the message: " + e.getMessage());
		} catch (BadRequestException e) {
			// aggregates two possible reasons of 400 error
			// empty problem code, empty problem name
			System.out.println("Bad request (empty problem code, empty problem name), details available in the message: " + e.getMessage());
		}
	}	
}
<?php
/**
 * Example presents error handling for updateProblem() API method
*/

use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;

// require library
require_once('../../../autoload.php');

// define access parameters
$accessToken = '<access_token>';
$endpoint = '<endpoint>';

// initialization
$client = new ProblemsClientV3($accessToken, $endpoint);

// API usage
$problemCode = 'NONEXISTING_CODE';
$newProblemName = 'New example problem name';

try {
	$response = $client->updateProblem($problemCode, $newProblemName);
} catch (SphereEngineResponseException $e) {
	if ($e->getCode() == 401) {
		echo 'Invalid access token';
	} elseif ($e->getCode() == 403) {
		echo 'Access to the problem is forbidden';
	} elseif ($e->getCode() == 400) {
		// aggregates two possible reasons of 400 error
		// empty problem code, empty problem name
		echo 'Bad request (empty problem code, empty problem name), details available in the message: ' . $e->getMessage();
	} elseif ($e->getCode() == 404) {
		// aggregates two possible reasons of 404 error
		// non existing problem or masterjudge
		echo 'Non existing resource (problem, masterjudge), details available in the message: ' . $e->getMessage();
	}
}
"""
Example presents error handling for problems.update() API method
"""
from sphere_engine import ProblemsClientV3
from sphere_engine.exceptions import SphereEngineException

# define access parameters
accessToken = '<access_token>'
endpoint = '<endpoint>'

# initialization
client = ProblemsClientV3(accessToken, endpoint)

# API usage
problemCode = 'NONEXISTING_CODE'
newProblemName = 'New example problem name'

try:
    response = client.problems.update(problemCode, newProblemName)
except SphereEngineException as e:
    if e.code == 401:
        print('Invalid access token')
    elif e.code == 403:
        print('Access to the problem is forbidden')
    elif e.code == 400:
        # aggregates two possible reasons of 400 error
        # empty problem code, empty problem name
        print('Bad request (empty problem code, empty problem name), details available in the message: ' + str(e))
    elif e.code == 404:
        # aggregates two possible reasons of 404 error
        # non existing problem or masterjudge
        print('Non existing resource (problem, masterjudge), details available in the message: ' + str(e))
var request = require('request');

var accessToken = '<access_token>';
var endpoint = '<endpoint>';

var problemCode = 'EXAMPLE';

var problemData = {
    name: 'New name'
};

request({
    
    url: 'http://' + endpoint + '/api/v3/problems/' + problemCode +  '?access_token=' + accessToken,
    method: 'PUT',
    form: problemData
}, function (error, response, body) {
    
    if (error) {
        console.log('Connection problem');
    }
    
    if (response) {
        if (response.statusCode === 200) {
            console.log('Problem updated');
        } else {
            if (response.statusCode === 401) {
                console.log('Invalid access token');
            }
            if (response.statusCode === 400) {
                console.log('Empty code or empty name');
            }
            if (response.statusCode === 403) {
                console.log('Access denied');
            }
            if (response.statusCode === 404) {
                console.log('Problem or masterjudge does not exist');
            }
        }
    }
});
GET /problems/:code/testcases?access_token=<access_token>
Retrieves list of problem test cases

Parameters:

Name Type Located in Description
access_token* string query access token
code* string path problem code

Response HTTP Code:

Code Description
200 success
401 unauthorized access
403 access denied
404 problem not found

Success Response:

Field Type Description
[].number integer test case number
[].active boolean if test is active
[].input.size integer input file size in bytes
[].input.uri string link to input file
[].output.size integer output file size in bytes
[].output.uri string link to output file
[].limits.time float time limit in seconds
[].judge.id integer judge id
[].judge.name string judge name
[].judge.uri string judge uri

Response example:

{
    "testcases": [
        {
            "number": 0,
            "active": true,
            "input": {
                "size": 7,
                "uri":"http://<endpoint>/api/v3/problems/EXPRBL/testcases/0/input-EXPRBL-0.txt?access_token=<access_token>"
            },
            "output": {
                "size": 9,
                "uri":"http://<endpoint>/api/v3/problems/EXPRBL/testcases/0/output-EXPRBL-0.txt?access_token=<access_token>"
            },
            "limits": {
                "time": 1
            },
            "judge": {
                "id": 1,
                "name": "Ignores extra whitespaces",
                "uri": "http://<endpoint>/api/v3/judges/1?access_token=<access_token>"
            }
        },
        {
            "number": 1,
            "active": false,
            "input": {
                "size": 3,
                "uri":"http://<endpoint>/api/v3/problems/EXPRBL/testcases/1/input-EXPRBL-1.txt?access_token=<access_token>"
            },
            "output": {
                "size": 2,
                "uri":"http://<endpoint>/api/v3/problems/EXPRBL/testcases/1/output-EXPRBL-1.txt?access_token=<access_token>"
            },
            "limits": {
                "time": 0.8
            },
            "judge": {
                "id": 1,
                "name": "Ignores extra whitespaces",
                "uri": "http://<endpoint>/api/v3/judges/1?access_token=<access_token>"
            }
        }
    ]
}

Examples

curl -X GET -H 'Content-Type: application/json' 'http://<endpoint>/api/v3/problems/:code/testcases?access_token=<access_token>'
package problems.problems;
/**
 * Example presents error handling for getProblemTestcases() API method   
 */

import javax.ws.rs.ForbiddenException;
import javax.ws.rs.NotAuthorizedException;
import javax.ws.rs.NotFoundException;

import com.SphereEngine.Api.ProblemsClientV3;
import com.google.gson.JsonObject;

public class getProblemTestcasesErrorHandling 
{

	public static void main(String[] args) 
	{
		ProblemsClientV3 client = new ProblemsClientV3(
				"<access_token>", 
				"<endpoint>");
		
		String problemCode = "NONEXISTING_CODE";
		
		try {
			JsonObject response = client.getProblemTestcases(problemCode);
		} catch (NotAuthorizedException e) {
			System.out.println("Invalid access token");
		} catch (ForbiddenException e) {
			System.out.println("Access to the problem is forbidden");
		} catch (NotFoundException e) {
			System.out.println("Problem does not exist");
		}
	}	
}
<?php
/**
 * Example presents error handling for getProblemTestcases() API method    
 */

use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;

// require library
require_once('../../../autoload.php');

// define access parameters
$accessToken = '<access_token>';
$endpoint = '<endpoint>';

// initialization
$client = new ProblemsClientV3($accessToken, $endpoint);

// API usage
$problemCode = 'NONEXISTING_CODE';

try {
	$response = $client->getProblemTestcases($problemCode);
} catch (SphereEngineResponseException $e) {
	if ($e->getCode() == 401) {
		echo 'Invalid access token';
	} elseif ($e->getCode() == 403) {
		echo 'Access to the problem is forbidden';
	} elseif ($e->getCode() == 404) {
		echo 'Problem does not exist';
	}
}
"""
Example presents error handling for problems.allTestcases() API method
"""
from sphere_engine import ProblemsClientV3
from sphere_engine.exceptions import SphereEngineException

# define access parameters
accessToken = '<access_token>'
endpoint = '<endpoint>'

# initialization
client = ProblemsClientV3(accessToken, endpoint)

# API usage
problemCode = 'NONEXISTING_CODE'

try:
    response = client.problems.allTestcases(problemCode)
except SphereEngineException as e:
    if e.code == 401:
        print('Invalid access token')
    elif e.code == 403:
        print('Access to the problem is forbidden')
    elif e.code == 404:
        print('Problem does not exist')
var request = require('request');

var accessToken = '<access_token>';
var endpoint = '<endpoint>';

var problemCode = 'EXAMPLE';

request({
    
    url: 'http://' + endpoint + '/api/v3/problems/' + problemCode + '/testcases?access_token=' + accessToken,
    method: 'GET'
}, function (error, response, body) {
    
    if (error) {
        console.log('Connection problem');
    }
    
    if (response) {
        if (response.statusCode === 200) {
            console.log(JSON.parse(response.body)); // list of testcases in JSON
        } else {
            if (response.statusCode === 401) {
                console.log('Invalid access token');
            }
            if (response.statusCode === 403) {
                console.log('Access denied');
            }
            if (response.statusCode === 404) {
                console.log('Problem not found');
            }
        }
    }
});
POST /problems/:code/testcases?access_token=<access_token>
Creates a problem test case

Parameters:

Name Type Located in Description
access_token* string query access token
code* string path problem code
input string formData input data, default: empty
output string formData output data, default: empty
timelimit float formData time limit in seconds, default: 1
judgeId integer formData judge id, default: 1 (Ignore extra whitespaces)
active boolean formData if test should be active, default: 1

Response HTTP Code:

Code Description
201 success
401 unauthorized access
403 access denied | access to judge forbidden
404 problem not found | judge not found
400 maximum number of test cases reached | timelimit is invalid
409 many test cases added at the same time

Success Response:

Field Type Description
number integer number of created test case

Response example:

{
    "number": 3
}

Examples

$ cat request.json
{
    "input": "input content", 
    "timelimit": 10, 
    "output": "output content"
}
        
$ curl -X POST -H 'Content-Type: application/json' "`cat request.json`" 'http://<endpoint>/api/v3/problems/:code/testcases?access_token=<access_token>'
package problems.problems;
/**
 * Example presents error handling for createProblemTestcase() API method  
 */

import javax.ws.rs.BadRequestException;
import javax.ws.rs.ForbiddenException;
import javax.ws.rs.NotAuthorizedException;
import javax.ws.rs.NotFoundException;

import com.SphereEngine.Api.ProblemsClientV3;
import com.google.gson.JsonObject;

public class createProblemTestcaseErrorHandling 
{

	public static void main(String[] args) 
	{
		ProblemsClientV3 client = new ProblemsClientV3(
				"<access_token>", 
				"<endpoint>");
		
		String code = "EXAMPLE";
		String input = "model input";
		String output = "model output";
		Double timelimit = 5.0;
		Integer nonexistingJudge = 9999;
		
		try {
			JsonObject response = client.createProblemTestcase(code, input, output, timelimit, nonexistingJudge);
			// response.get("number") stores the number of created testcase
		} catch (NotAuthorizedException e) {
			System.out.println("Invalid access token");
		} catch (ForbiddenException e) {
			System.out.println("Access to the problem is forbidden");
		} catch (NotFoundException e) {
			// aggregates two possible reasons of 400 error
			// non existing problem and judge
			System.out.println("Non existing resource (problem or judge), details available in the message: " + e.getMessage());
		}
	}	
}
<?php
/**
 * Example presents error handling for createProblemTestcase() API method  
*/

use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;

// require library
require_once('../../../autoload.php');

// define access parameters
$accessToken = '<access_token>';
$endpoint = '<endpoint>';

// initialization
$client = new ProblemsClientV3($accessToken, $endpoint);

// API usage
$code = "EXAMPLE";
$input = "model input";
$output = "model output";
$timelimit = 5;
$nonexistingJudge = 9999;

try {
	$response = $client->createProblemTestcase($code, $input, $output, $timelimit, $nonexistingJudge);
	// response['number'] stores the number of created testcase
} catch (SphereEngineResponseException $e) {
	if ($e->getCode() == 401) {
		echo 'Invalid access token';
	} elseif ($e->getCode() == 403) {
		echo 'Access to the problem is forbidden';
	} elseif ($e->getCode() == 404) {
		// aggregates two possible reasons of 400 error
		// non existing problem and judge
		echo 'Non existing resource (problem or judge), details available in the message: ' . $e->getMessage();
	}
}
"""
Example presents error handling for createProblemTestcase() API method
"""
from sphere_engine import ProblemsClientV3
from sphere_engine.exceptions import SphereEngineException

# define access parameters
accessToken = '<access_token>'
endpoint = '<endpoint>'

# initialization
client = ProblemsClientV3(accessToken, endpoint)

# API usage
code = 'EXAMPLE'
input = 'model input'
output = 'model output'
timelimit = 5
nonexistingJudge = 9999

try:
    response = client.problems.createTestcase(code, input, output, timelimit, nonexistingJudge)
    # response['number'] stores the number of created testcase
except SphereEngineException as e:
    if e.code == 401:
        print('Invalid access token')
    elif e.code == 403:
        print('Access to the problem is forbidden')
    elif e.code == 404:
        # aggregates two possible reasons of 400 error
        # non existing problem and judge
        print('Non existing resource (problem or judge), details available in the message: ' + str(e))
var request = require('request');

var accessToken = '<access_token>';
var endpoint = '<endpoint>';

var problemCode = 'EXAMPLE';

var testcaseData = {
    input: 'Input',
    output: 'Output',
    timelimit: 5,
    judgeId: 1
};

request({
    
    url: 'http://' + endpoint + '/api/v3/problems/' + problemCode +  '/testcases?access_token=' + accessToken,
    method: 'POST',
    form: testcaseData
}, function (error, response, body) {
    
    if (error) {
        console.log('Connection problem');
    }
    
    if (response) {
        if (response.statusCode === 201) {
            console.log(JSON.parse(response.body)); // testcase data in JSON
        }
        else {
            if (response.statusCode === 401) {
                console.log('Invalid access token');
            }
            if (response.statusCode === 400) {
                console.log('Maximum number of test cases reached or timelimit is invalid');
            }
            if (response.statusCode === 403) {
                console.log('Access denied');
            }
            if (response.statusCode === 404) {
                console.log('Problem or judge does not exist');
            }
			if (response.statusCode === 409) {
                console.log('Many test cases added at the same time ');
            }
        }
    }
});
GET /problems/:code/testcases/:number?access_token=<access_token>
Retrieves problem test case

Parameters:

Name Type Located in Description
access_token* string query access token
code* string path problem code
number* integer path test case number

Response HTTP Code:

Code Description
200 success
401 unauthorized access
403 access denied
404 problem not found | test case not found

Success Response:

Field Type Description
number integer test case number
active boolean if test is active
input.size integer input file size in bytes
input.uri string link to input file
output.size integer output file size in bytes
output.uri string link to output file
limits.time float time limit in seconds
judge.id integer judge id
judge.name string judge name
judge.uri string judge uri

Response example:

{
    "number": 0,
    "active": true,
    "input": {
        "size":7,
        "uri":"http://<endpoint>/api/v3/problems/EXPRBL/testcases/0/input-EXPRBL-0.txt?access_token=<access_token>"
    },
    "output":{
        "size":9,
        "uri":"http://<endpoint>/api/v3/problems/EXPRBL/testcases/0/output-EXPRBL-0.txt?access_token=<access_token>"
    },
    "limits": {
        "time": 1
    },
    "judge": {
        "id": 1,
        "name": "Ignores extra whitespaces",
        "uri": "http://<endpoint>/api/v3/judges/1?access_token=<access_token>"
    }
}

Examples

curl -X GET -H 'Content-Type: application/json' 'http://<endpoint>/api/v3/problems/:code/testcases/:number?access_token=<access_token>'
package problems.problems;
/**
 * Example presents error handling for getProblemTestcase() API method   
 */

import javax.ws.rs.ForbiddenException;
import javax.ws.rs.NotAuthorizedException;
import javax.ws.rs.NotFoundException;

import com.SphereEngine.Api.ProblemsClientV3;
import com.google.gson.JsonObject;

public class getProblemTestcaseErrorHandling 
{

	public static void main(String[] args) 
	{
		ProblemsClientV3 client = new ProblemsClientV3(
				"<access_token>", 
				"<endpoint>");
		
		String problemCode = "TEST";
		Integer nonexistingTestcaseNumber = 999;
		
		try {
			JsonObject response = client.getProblemTestcase(problemCode, nonexistingTestcaseNumber);
		} catch (NotAuthorizedException e) {
			System.out.println("Invalid access token");
		} catch (ForbiddenException e) {
			System.out.println("Access to the problem is forbidden");
		} catch (NotFoundException e) {
			// aggregates two possible reasons of 404 error
			// non existing problem or testcase
			System.out.println("Non existing resource (problem, testcase), details available in the message: " + e.getMessage());
		}
	}	
}
<?php
/**
 * Example presents error handling for getProblemTestcase() API method    
 */

use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;

// require library
require_once('../../../autoload.php');

// define access parameters
$accessToken = '<access_token>';
$endpoint = '<endpoint>';

// initialization
$client = new ProblemsClientV3($accessToken, $endpoint);

// API usage
$problemCode = 'TEST';
$nonexistingTestcaseNumber = 999;

try {
	$response = $client->getProblemTestcase($problemCode, $nonexistingTestcaseNumber);
} catch (SphereEngineResponseException $e) {
	if ($e->getCode() == 401) {
		echo 'Invalid access token';
	} elseif ($e->getCode() == 403) {
		echo 'Access to the problem is forbidden';
	} elseif ($e->getCode() == 404) {
		// aggregates two possible reasons of 404 error
		// non existing problem or testcase
		echo 'Non existing resource (problem, testcase), details available in the message: ' . $e->getMessage();
	}
}
"""
Example presents error handling for problems.getTestcase() API method
"""
from sphere_engine import ProblemsClientV3
from sphere_engine.exceptions import SphereEngineException

# define access parameters
accessToken = '<access_token>'
endpoint = '<endpoint>'

# initialization
client = ProblemsClientV3(accessToken, endpoint)

# API usage
problemCode = 'TEST'
nonexistingTestcaseNumber = 999

try:
    response = client.problems.getTestcase(problemCode, nonexistingTestcaseNumber)
except SphereEngineException as e:
    if e.code == 401:
        print('Invalid access token')
    elif e.code == 403:
        print('Access to the problem is forbidden')
    elif e.code == 404:
        # aggregates two possible reasons of 404 error
        # non existing problem or testcase
        print('Non existing resource (problem, testcase), details available in the message: ' + str(e))
var request = require('request');

var accessToken = '<access_token>';
var endpoint = '<endpoint>';

var problemCode = 'EXAMPLE';
var testcaseNumber = 0;

request({
    
    url: 'http://' + endpoint + '/api/v3/problems/' + problemCode + '/testcases/' + testcaseNumber + '?access_token=' + accessToken,
    method: 'GET'
}, function (error, response, body) {
    
    if (error) {
        console.log('Connection problem');
    }
    
    if (response) {
        if (response.statusCode === 200) {
            console.log(JSON.parse(response.body)); // testcase data in JSON
        }
        else {
            if (response.statusCode === 401) {
                console.log('Invalid access token');
            }
            if (response.statusCode === 403) {
                console.log('Access denied');
            }
            if (response.statusCode === 404) {
                console.log('Testcase or problem not found');
            }
        }
    }
});
PUT /problems/:code/testcases/:number?access_token=<access_token>
Updates the problem test case

Parameters:

Name Type Located in Description
access_token* string query access token
code* string path problem code
number* integer path test case number
input string formData input data
output string formData output data
timelimit float formData time limit in seconds
judgeId integer formData judge id

Response HTTP Code:

Code Description
200 success
401 unauthorized access
403 access denied | access to judge forbidden
404 problem not found | test case not found | judge not found

Response example:

{}

Examples

$ cat request.json
{
    "input": "updated content", 
    "timelimit": 9, 
    "output": "updated content"
}
        
curl -X PUT -H 'Content-Type: application/json' -d "`cat request.json`" 'http://<endpoint>/api/v3/problems/:code/testcases/:number?access_token=<access_token>'
package problems.problems;
/**
 * Example presents error handling for updateProblemTestcase() API method  
 */

import javax.ws.rs.BadRequestException;
import javax.ws.rs.ForbiddenException;
import javax.ws.rs.NotAuthorizedException;
import javax.ws.rs.NotFoundException;

import com.SphereEngine.Api.ProblemsClientV3;
import com.google.gson.JsonObject;

public class updateProblemTestcaseErrorHandling 
{

	public static void main(String[] args) 
	{
		ProblemsClientV3 client = new ProblemsClientV3(
				"<access_token>", 
				"<endpoint>");
		
		String problemCode = "TEST";
		Integer testcaseNumber = 0;
		Integer newNonexistingJudge = 9999;
		
		try {
			JsonObject response = client.updateProblemTestcase(problemCode, testcaseNumber, null, null, null, newNonexistingJudge);
		} catch (NotAuthorizedException e) {
			System.out.println("Invalid access token");
		} catch (ForbiddenException e) {
			System.out.println("Access to the problem is forbidden");
		} catch (NotFoundException e) {
			// aggregates three possible reasons of 404 error
			// non existing problem, testcase or judge
			System.out.println("Non existing resource (problem, testcase or judge), details available in the message: " + e.getMessage());
		}
	}	
}
<?php
/**
 * Example presents error handling for updateProblemTestcase() API method    
 */

use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;

// require library
require_once('../../../autoload.php');

// define access parameters
$accessToken = '<access_token>';
$endpoint = '<endpoint>';

// initialization
$client = new ProblemsClientV3($accessToken, $endpoint);

// API usage
$problemCode = 'TEST';
$testcaseNumber = 0;
$newNonexistingJudge = 9999; 

try {
	$response = $client->updateProblemTestcase($problemCode, $testcaseNumber, null, null, null, $newNonexistingJudge);
} catch (SphereEngineResponseException $e) {
	if ($e->getCode() == 401) {
		echo 'Invalid access token';
	} elseif ($e->getCode() == 403) {
		echo 'Access to the problem is forbidden';
	} elseif ($e->getCode() == 404) {
		// aggregates three possible reasons of 404 error
		// non existing problem, testcase or judge
		echo 'Non existing resource (problem, testcase or judge), details available in the message: ' . $e->getMessage();
	}
}
"""
Example presents error handling for problems.updateTestcase() API method
"""
from sphere_engine import ProblemsClientV3
from sphere_engine.exceptions import SphereEngineException

# define access parameters
accessToken = '<access_token>'
endpoint = '<endpoint>'

# initialization
client = ProblemsClientV3(accessToken, endpoint)

# API usage
problemCode = 'TEST'
testcaseNumber = 0
newNonexistingJudge = 9999

try:
    response = client.problems.updateTestcase(problemCode, testcaseNumber, None, None, None, newNonexistingJudge)
except SphereEngineException as e:
    if e.code == 401:
        print('Invalid access token')
    elif e.code == 403:
        print('Access to the problem is forbidden')
    elif e.code == 404:
        # aggregates three possible reasons of 404 error
        # non existing problem, testcase or judge
        print('Non existing resource (problem, testcase or judge), details available in the message: ' + str(e))
var request = require('request');

var accessToken = '<access_token>';
var endpoint = '<endpoint>';

var problemCode = 'EXAMPLE';
var testcaseNumber = 0;

var testcaseData = {
    input: 'New input'
};

request({
    
    url: 'http://' + endpoint + '/api/v3/problems/' + problemCode +  '/testcases/' + testcaseNumber + '?access_token=' + accessToken,
    method: 'PUT',
    form: testcaseData
}, function (error, response, body) {
    
    if (error) {
        console.log('Connection problem');
    }
    
    if (response) {
        if (response.statusCode === 200) {
            console.log('Testcase updated');
        } else {
            if (response.statusCode === 401) {
                console.log('Invalid access token');
            }
            if (response.statusCode === 400) {
                console.log('Empty code or empty name');
            }
            if (response.statusCode === 403) {
                console.log('Access denied');
            }
            if (response.statusCode === 404) {
                console.log('Testcase, problem or judge does not exist');
            }
        }
    }
});
GET /problems/:code/testcases/:number/:filename?access_token=<access_token>
Retrieves Problem test case file

Parameters:

Name Type Located in Description
access_token* string query access token
code* string path problem code
number* integer path test case number
filename* string path stream name, enum: input|output

Response HTTP Code:

Code Description
200 success
401 unauthorized access
403 access denied
400 number must be integer
404 problem not found | test case not found | file not found

Response example:

Raw data from selected file.

Examples

curl -X GET -H 'Content-Type: application/json' 'http://<endpoint>/api/v3/problems/:code/testcases/:number/:filename?access_token=<access_token>'
package problems.problems;
/**
 * Example presents error handling for getProblemTestcaseFile() API method   
 */

import javax.ws.rs.ForbiddenException;
import javax.ws.rs.NotAuthorizedException;
import javax.ws.rs.NotFoundException;

import com.SphereEngine.Api.ProblemsClientV3;
import com.google.gson.JsonObject;

public class getProblemTestcaseFileErrorHandling 
{

	public static void main(String[] args) 
	{
		ProblemsClientV3 client = new ProblemsClientV3(
				"<access_token>", 
				"<endpoint>");
		
		String problemCode = "TEST";
		Integer testcaseNumber = 0;
		String nonexistingFile = "nonexistingFile";
		
		try {
			String response = client.getProblemTestcaseFile(problemCode, testcaseNumber, nonexistingFile);
		} catch (NotAuthorizedException e) {
			System.out.println("Invalid access token");
		} catch (ForbiddenException e) {
			System.out.println("Access to the problem is forbidden");
		} catch (NotFoundException e) {
			// aggregates three possible reasons of 404 error
			// non existing problem, testcase or file
			System.out.println("Non existing resource (problem, testcase or file), details available in the message: " + e.getMessage());
		}
	}	
}
<?php
/**
 * Example presents error handling for getProblemTestcaseFile() API method    
 */

use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;

// require library
require_once('../../../autoload.php');

// define access parameters
$accessToken = '<access_token>';
$endpoint = '<endpoint>';

// initialization
$client = new ProblemsClientV3($accessToken, $endpoint);

// API usage
$problemCode = 'TEST';
$testcaseNumber = 0;
$nonexistingFile = 'nonexistingFile';

try {
	$response = $client->getProblemTestcaseFile($problemCode, $testcaseNumber, $nonexistingFile);
} catch (SphereEngineResponseException $e) {
	if ($e->getCode() == 401) {
		echo 'Invalid access token';
	} elseif ($e->getCode() == 403) {
		echo 'Access to the problem is forbidden';
	} elseif ($e->getCode() == 404) {
		// aggregates three possible reasons of 404 error
		// non existing problem, testcase or file
		echo 'Non existing resource (problem, testcase or file), details available in the message: ' . $e->getMessage();
	}
}
"""
Example presents error handling for problems.getTestcaseFile() API method
"""
from sphere_engine import ProblemsClientV3
from sphere_engine.exceptions import SphereEngineException

# define access parameters
accessToken = '<access_token>'
endpoint = '<endpoint>'

# initialization
client = ProblemsClientV3(accessToken, endpoint)

# API usage
problemCode = 'TEST'
testcaseNumber = 0
nonexistingFile = 'nonexistingFile'

try:
    response = client.problems.getTestcaseFile(problemCode, testcaseNumber, nonexistingFile)
except SphereEngineException as e:
    if e.code == 401:
        print('Invalid access token')
    elif e.code == 403:
        print('Access to the problem is forbidden')
    elif e.code == 404:
        # aggregates three possible reasons of 404 error
        # non existing problem, testcase or file
        print('Non existing resource (problem, testcase or file), details available in the message: ' + str(e))
var request = require('request');

var accessToken = '<access_token>';
var endpoint = '<endpoint>';

var problemCode = 'EXAMPLE';
var testcaseNumber = 0;
var fileName = '<file_name>'

request({
    
    url: 'http://' + endpoint + '/api/v3/problems/' + problemCode + '/testcases/' + testcaseNumber + '/' + fileName + '?access_token=' + accessToken,
    method: 'GET'
}, function (error, response, body) {
    
    if (error) {
        console.log('Connection problem');
    }
    
    if (response) {
        if (response.statusCode === 200) {
            console.log(response.body); // raw data from selected file
        } else {
            if (response.statusCode === 401) {
                console.log('Invalid access token');
            }
            if (response.statusCode === 403) {
                console.log('Access denied');
            }
            if (response.statusCode === 404) {
                console.log('File, testcase or problem not found');
            }
        }
    }
});
GET /judges?access_token=<access_token>
Returns the list of judges of the quantity given by limit parameter starting from the offset parameter.

Parameters:

Name Type Located in Description
access_token* string query access token
limit integer query limit of judges to get, default: 10, max: 100
offset integer query offset, default: 0
type string query judge type, enum: testcase|master

Response HTTP Code:

Code Description
200 success
401 unauthorized access

Success Response:

Field Type Description
items[].id integer judge id
items[].name string judge name
items[].uri string judge more details
items[].type string judge type
paging.limit integer items per page
paging.offset integer first item
paging.total integer total number of items
paging.pages integer total number of pages for the current limit
paging.next string next page, link or empty if no page
paging.prev string previous page, link or empty if no page

Response example:

{
    "items": [
        {
            "id": 1,
            "name": "Ignores extra whitespaces",
            "uri": "http://<endpoint>/api/v3/judges/1?access_token=<access_token>",
            "type": "testcase"
        },
        {
            "id": 2,
            "name":"Ignores FP rounding up to 10^-2",
            "uri": "http://<endpoint>/api/v3/judges/2?access_token=<access_token>",
            "type": "testcase"
        }
    ],
    "paging": {
        "limit": 2,
        "offset": 4,
        "total": 9,
        "pages": 5,
        "prev": "http://<endpoint>/api/v3/judges?offset=2&access_token=<access_token>",
        "next": "http://<endpoint>/api/v3/judges?offset=6&access_token=<access_token>"
    }
}

Examples

curl -X GET -H 'Content-Type: application/json' 'http://<endpoint>/api/v3/judges?access_token=<access_token>'
package problems.judges;
/**
 * Example presents usage of the successful getJudges() API method  
 */

import com.SphereEngine.Api.ProblemsClientV3;
import com.google.gson.JsonObject;

public class getJudges 
{

	public static void main(String[] args) 
	{
		ProblemsClientV3 client = new ProblemsClientV3(
				"<access_token>", 
				"<endpoint>");
		
		JsonObject response = client.getJudges();
	}	
}
<?php
/**
 * Example presents usage of the successful getJudges() API method  
 */

use SphereEngine\Api\ProblemsClientV3;

// require library
require_once('../../../autoload.php');

// define access parameters
$accessToken = '<access_token>';
$endpoint = '<endpoint>';

// initialization
$client = new ProblemsClientV3($accessToken, $endpoint);

// API usage
$response = $client->getJudges();
"""
Example presents usage of the successful judges.all() API method
"""
from sphere_engine import ProblemsClientV3

# define access parameters
accessToken = '<access_token>'
endpoint = '<endpoint>'

# initialization
client = ProblemsClientV3(accessToken, endpoint)

# API usage
response = client.judges.all()
var request = require('request');

var accessToken = '<access_token>';
var endpoint = '<endpoint>';

request({
    
    url: 'http://' + endpoint + '/api/v3/judges?access_token=' + accessToken,
    method: 'GET'
}, function (error, response, body) {
    
    if (error) {
        console.log('Connection problem');
    }
    
    if (response) {
        if (response.statusCode === 200) {
            console.log(JSON.parse(response.body)); // list of judges in JSON
        } else {
            if (response.statusCode === 401) {
                console.log('Invalid access token');
            }
        }
    }
});
POST /judges?access_token=<access_token>
Creates a new judge

Parameters:

Name Type Located in Description
access_token* string query access token
name string formData judge name, default: empty
type string formData judge type, testcase|master, default: testcase
compilerId integer formData compiler id, default: 1 (C++)
source* string formData source code

Response HTTP Code:

Code Description
201 success
401 unauthorized access
403 compiler not available
400 empty source
404 compiler not found

Success Response:

Field Type Description
id integer id of created judge

Response example:

{
    "id": 42
}

Examples

$ cat request.json
{
    "source": "<source code>"
}

$ curl -X POST -H 'Content-Type: application/json' -d "`cat request.json`" 'http://<endpoint>/api/v3/judges?access_token=<access_token>'
package problems.judges;
/**
 * Example presents error handling for createJudge() API method  
 */

import javax.ws.rs.BadRequestException;
import javax.ws.rs.NotAuthorizedException;
import javax.ws.rs.NotFoundException;

import com.SphereEngine.Api.ProblemsClientV3;
import com.google.gson.JsonObject;

public class createJudgeErrorHandling 
{

	public static void main(String[] args) 
	{
		ProblemsClientV3 client = new ProblemsClientV3(
				"<access_token>", 
				"<endpoint>");
		
		String source = "<source code>";
		Integer nonexistingCompiler = 9999;
		
		try {
			JsonObject response = client.createJudge(source, nonexistingCompiler);
			// response.get("id") stores the ID of the created judge
		} catch (NotAuthorizedException e) {
			System.out.println("Invalid access token");
		} catch (NotFoundException e) {
			System.out.println("Compiler does not exist");
		} catch (BadRequestException e) {
			System.out.println("Empty source");
		}
	}	
}
<?php
/**
 * Example presents error handling for createJudge() API method  
*/

use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;

// require library
require_once('../../../autoload.php');

// define access parameters
$accessToken = '<access_token>';
$endpoint = '<endpoint>';

// initialization
$client = new ProblemsClientV3($accessToken, $endpoint);

// API usage
$source = '<source code>';
$nonexisting_compiler = 9999;

try {
	$response = $client->createJudge($source, $nonexisting_compiler);
	// response['id'] stores the ID of the created judge
} catch (SphereEngineResponseException $e) {
	if ($e->getCode() == 401) {
		echo 'Invalid access token';
	} elseif ($e->getCode() == 400) {
		echo 'Empty source';
	} elseif ($e->getCode() == 404) {
		echo 'Compiler does not exist';
	}
}
"""
Example presents error handling for judges.create() API method
"""
from sphere_engine import ProblemsClientV3
from sphere_engine.exceptions import SphereEngineException

# define access parameters
accessToken = '<access_token>'
endpoint = '<endpoint>'

# initialization
client = ProblemsClientV3(accessToken, endpoint)

# API usage
source = '<source code>'
nonexisting_compiler = 9999

try:
    response = client.judges.create(source, nonexisting_compiler)
    # response['id'] stores the ID of the created judge
except SphereEngineException as e:
    if e.code == 401:
        print('Invalid access token')
    elif e.code == 400:
        print('Empty source')
    elif e.code == 404:
        print('Compiler does not exist')
var request = require('request');

var accessToken = '<access_token>';
var endpoint = '<endpoint>';

var judgeData = {
    compilerId: 11,
    source: '<source_code>'
};

request({
    
    url: 'http://' + endpoint + '/api/v3/judges?access_token=' + accessToken,
    method: 'POST',
    form: judgeData
}, function (error, response, body) {
    
    if (error) {
        console.log('Connection problem');
    }
    
    if (response) {
        if (response.statusCode === 201) {
            console.log(JSON.parse(response.body)); // judge data in JSON
        } else {
            if (response.statusCode === 401) {
                console.log('Invalid access token');
            }
            if (response.statusCode === 400) {
                console.log('Empty source code');
            }	
            if (response.statusCode === 404) {
                console.log('Compiler does not exist');
            }
        }
    }
});
GET /judges/:id?access_token=<access_token>
Retrieves an existing judge

Parameters:

Name Type Located in Description
access_token* string query access token
id* integer path judge id

Response HTTP Code:

Code Description
200 success
401 unauthorized access
403 access denied
404 judge not found

Success Response:

Field Type Description
id integer judge id
name string judge name
source string judge source
compiler.id integer compiler id
compiler.name string compiler name
type string type of the judge, enum: testcase|master

Response example:

{
    "id": 1,
    "name": "Ignores extra whitespaces",
    "source": "judge source code",
    "compiler": {
        "id": 1,
        "name": "C++"
    },
    "type": "testcase"
}

Examples

curl -X GET -H 'Content-Type: application/json' 'http://<endpoint>/api/v3/judges/:id?access_token=<access_token>'
package problems.judges;
/**
 * Example presents error handling for getJudge() API method   
 */

import javax.ws.rs.ForbiddenException;
import javax.ws.rs.NotAuthorizedException;
import javax.ws.rs.NotFoundException;

import com.SphereEngine.Api.ProblemsClientV3;
import com.google.gson.JsonObject;

public class getJudgeErrorHandling 
{

	public static void main(String[] args) 
	{
		ProblemsClientV3 client = new ProblemsClientV3(
				"<access_token>", 
				"<endpoint>");
		
		Integer nonexistingJudgeId = 999999;
		
		try {
			JsonObject response = client.getJudge(nonexistingJudgeId);
		} catch (NotAuthorizedException e) {
			System.out.println("Invalid access token");
		} catch (ForbiddenException e) {
			System.out.println("Access to the judge is forbidden");
		} catch (NotFoundException e) {
			System.out.println("Judge does not exist");
		}
	}	
}
<?php
/**
 * Example presents error handling for getJudge() API method    
 */

use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;

// require library
require_once('../../../autoload.php');

// define access parameters
$accessToken = '<access_token>';
$endpoint = '<endpoint>';

// initialization
$client = new ProblemsClientV3($accessToken, $endpoint);

// API usage
$nonexisting_judge_id = 999999;
try {
	$response = $client->getJudge($nonexisting_judge_id);
} catch (SphereEngineResponseException $e) {
	if ($e->getCode() == 401) {
		echo 'Invalid access token';
	} elseif ($e->getCode() == 404) {
		echo 'Judge does not exist';
	} elseif ($e->getCode() == 403) {
		echo 'Access to the judge is forbidden';
	}
}
"""
Example presents error handling for judges.get() API method
"""
from sphere_engine import ProblemsClientV3
from sphere_engine.exceptions import SphereEngineException

# define access parameters
accessToken = '<access_token>'
endpoint = '<endpoint>'

# initialization
client = ProblemsClientV3(accessToken, endpoint)

# API usage
nonexisting_judge_id = 999999
try:
    response = client.judges.get(nonexisting_judge_id)
except SphereEngineException as e:
    if e.code == 401:
        print('Invalid access token')
    elif e.code == 404:
        print('Judge does not exist')
    elif e.code == 403:
        print('Access to the judge is forbidden')
var request = require('request');

var accessToken = '<access_token>';
var endpoint = '<endpoint>';

var judgeId = 1;

request({
    
    url: 'http://' + endpoint + '/api/v3/judges/' + judgeId + '?access_token=' + accessToken,
    method: 'GET'
}, function (error, response, body) {
    
    if (error) {
        console.log('Connection problem');
    }
    
    if (response) {
        if (response.statusCode === 200) {
            console.log(JSON.parse(response.body)); // judge data in JSON
        } else {
            if (response.statusCode === 401) {
                console.log('Invalid access token');
            }
            if (response.statusCode === 403) {
                console.log('Access denied');
            }
            if (response.statusCode === 404) {
                console.log('Submision not found');
            }
        }
    }
});
PUT /judges/:id?access_token=<access_token>
Updates an existing judge

Parameters:

Name Type Located in Description
access_token* string query access token
id* integer path judge id
name string formData judge name
compilerId integer formData compiler id
source string formData source code

Response HTTP Code:

Code Description
200 success
401 unauthorized access
403 access denied | compiler not available
400 empty source
404 judge not found | compiler not found

Response example:

{}

Examples

$ cat request.json
{
    "name": "<new_name>"
}
        
$ curl -X PUT -H 'Content-Type: application/json' -d "`cat request.json`" 'http://<endpoint>/api/v3/judges/:id?access_token=<access_token>'
package problems.judges;
/**
 * Example presents error handling for updateJudge() API method  
 */

import javax.ws.rs.BadRequestException;
import javax.ws.rs.ForbiddenException;
import javax.ws.rs.NotAuthorizedException;
import javax.ws.rs.NotFoundException;

import com.SphereEngine.Api.ProblemsClientV3;
import com.google.gson.JsonObject;

public class updateJudgeErrorHandling 
{

	public static void main(String[] args) 
	{
		ProblemsClientV3 client = new ProblemsClientV3(
				"<access_token>", 
				"<endpoint>");
		
		String source = "<source code>";
		Integer nonexistingCompiler = 9999;
		
		try {
			JsonObject response = client.updateJudge(1, source, nonexistingCompiler);
		} catch (NotAuthorizedException e) {
			System.out.println("Invalid access token");
		} catch (ForbiddenException e) {
			System.out.println("Access to the judge is forbidden");
		} catch (NotFoundException e) {
			// aggregates two possible reasons of 404 error
			// non existing judge or compiler
			System.out.println("Non existing resource (judge, compiler), details available in the message: " + e.getMessage());
		} catch (BadRequestException e) {
			System.out.println("Empty source");
		}
	}	
}
<?php
/**
 * Example presents error handling for updateJudge() API method  
*/

use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;

// require library
require_once('../../../autoload.php');

// define access parameters
$accessToken = '<access_token>';
$endpoint = '<endpoint>';

// initialization
$client = new ProblemsClientV3($accessToken, $endpoint);

// API usage
$source = '<source code>';
$nonexistingCompiler = 9999;

try {
	$response = $client->updateJudge(1, $source, $nonexistingCompiler);
} catch (SphereEngineResponseException $e) {
	if ($e->getCode() == 401) {
		echo 'Invalid access token';
	} elseif ($e->getCode() == 400) {
		echo 'Empty source';
	} elseif ($e->getCode() == 403) {
		echo 'Access to the judge is forbidden';
	} elseif ($e->getCode() == 404) {
		// aggregates two possible reasons of 404 error
		// non existing judge or compiler
		echo 'Non existing resource (judge, compiler), details available in the message: ' . $e->getMessage();
	}
}
"""
Example presents error handling for judges.update() API method
"""
from sphere_engine import ProblemsClientV3
from sphere_engine.exceptions import SphereEngineException

# define access parameters
accessToken = '<access_token>'
endpoint = '<endpoint>'

# initialization
client = ProblemsClientV3(accessToken, endpoint)

# API usage
source = '<source code>'
nonexistingCompiler = 9999

try:
    response = client.judges.update(1, source, nonexistingCompiler)
except SphereEngineException as e:
    if e.code == 401:
        print('Invalid access token')
    elif e.code == 400:
        print('Empty source')
    elif e.code == 403:
        print('Access to the judge is forbidden')
    elif e.code == 404:
        # aggregates two possible reasons of 404 error
        # non existing judge or compiler
        print('Non existing resource (judge, compiler), details available in the message: ' + str(e))
var request = require('request');

var accessToken = '<access_token>';
var endpoint = '<endpoint>';

var judgeId = 1;

var judgeData = {
    compilerId: 11,
    source: '<source_code>'
};

request({
    
    url: 'http://' + endpoint + '/api/v3/judges/' + judgeId +  '?access_token=' + accessToken,
    method: 'PUT',
    form: judgeData
}, function (error, response, body) {
	
    if (error) {
        console.log('Connection problem');
    }
    
    if (response) {
        if (response.statusCode === 200) {
            console.log('Judge updated');
        } else {
            if (response.statusCode === 401) {
                console.log('Invalid access token');
            }
            if (response.statusCode === 400) {
                console.log('Empty source code');
            }
            if (response.statusCode === 403) {
                console.log('Access denied');
            }
            if (response.statusCode === 404) {
                console.log('Judge or compiler does not exist');
            }
        }
    }
});