- Sphere Engine overview
- Compilers
- Overview
- API integration
- JavaScript widget
- Resources
- Problems
- Overview
- API integration
- JavaScript widget
- Handbook
- Resources
- Containers
- Overview
- API
- Workspaces
- Handbook
- RESOURCES
- Programming languages
- Modules comparison
- Webhooks
- API Changelog
- FAQ
Important: If you are just starting with Sphere Engine Problems API, please use its latest version.
Introduction
This document describes Sphere Engine Problems web service. It is explained here how the methods should be used and how to interpret data returned by them. All URLs referenced in the documentation have the base https://<customer_id>.problems.sphere-engine.com/api/v3
.
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 80 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 https://<customer_id>.problems.sphere-engine.com/api/v3/
link called an endpoint. For example, the /test API call is reachable at https://<customer_id>.problems.sphere-engine.com/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 the stage of the program's execution. We can divide the possible values of statuses into two separate groups.
Statuses from the first group are called transitional statuses. All of them are used during the 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 the 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 stopped 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 the 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:
- submit source code,
- wait 5 seconds,
- retrieve submission details,
- (optional) present current status to the user,
- if the status <= 8 go back to step (2),
- (optional) present all execution details to the user.
The following diagram presents the idea of this algorithm:

API methods
For testing purposes. This method should return testing string.
Request parameters
Name | Located in | Type | Description |
---|---|---|---|
access_token |
query | string | access token |
Response HTTP Code
Code | Description |
---|---|
200 | success |
401 | unauthorized access |
Examples
curl -X GET 'https://<endpoint>/api/v3/test?access_token=<access_token>'
package problems;
/**
* Example presents usage of the successful test() API method
*/
import com.SphereEngine.Api.ProblemsClientV3;
import com.SphereEngine.Api.Exception.NotAuthorizedException;
import com.SphereEngine.Api.Exception.ClientException;
import com.SphereEngine.Api.Exception.ConnectionException;
import com.google.gson.JsonObject;
public class test
{
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");
} catch (ClientException e) {
System.out.println(e.getMessage());
} catch (ConnectionException e) {
System.out.println(e.getMessage());
}
}
}
<?php
/**
* Example presents usage of the successful test() API method
*/
use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;
// require library
require_once('../../../vendor/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');
// define access parameters
var accessToken = '<access_token>';
var endpoint = '<endpoint>';
// send request
request({
url: 'https://' + endpoint + '/api/v3/test?access_token=' + accessToken,
method: 'GET'
}, function (error, response, body) {
if (error) {
console.log('Connection problem');
}
// process response
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) {
// define access parameters
string endpoint = "<endpoint>";
string accessToken = "<access_token>";
try {
WebClient client = new WebClient();
// send request
byte[] responseBytes = client.DownloadData("https://" + endpoint + "/api/v3/test?access_token=" + accessToken);
string responseBody = Encoding.UTF8.GetString(responseBytes);
// process response
Console.WriteLine(responseBody);
} catch (WebException exception) {
WebResponse response = exception.Response;
HttpStatusCode statusCode = (((HttpWebResponse) response).StatusCode);
// fetch errors
if (statusCode == HttpStatusCode.Unauthorized) {
Console.WriteLine("Invalid access token");
}
response.Close();
}
}
}
}
require 'net/http'
require 'uri'
require 'json'
# define access parameters
endpoint = "<endpoint>"
access_token = "<access_token>"
# send request
uri = URI.parse("https://" + endpoint + "/api/v3/test?access_token=" + access_token)
http = Net::HTTP.new(uri.host, uri.port)
begin
response = http.request(Net::HTTP::Get.new(uri.request_uri))
# process response
case response
when Net::HTTPSuccess
puts JSON.parse(response.body)
when Net::HTTPUnauthorized
puts "Invalid access token"
end
rescue => e
puts "Connection error"
end
Response example
{
"message": "You can use Sphere Engine Problems API."
}
Returns a list of supported compilers.
Request parameters
Name | Located in | Type | Description |
---|---|---|---|
access_token |
query | string | 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[].highlights | string | syntax highlighting identifier for Highlights |
items[].rouge | string | syntax highlighting identifier for Rouge |
items[].codemirror | string | syntax highlighting identifier for CodeMirror |
items[].highlightjs | string | syntax highlighting identifier for highlight.js |
items[].prism | string | syntax highlighting identifier for Prism |
items[].monaco | string | syntax highlighting identifier for Monaco Editor |
items[].code_prettify | string | syntax highlighting identifier for Google Code Prettify |
Examples
curl -X GET 'https://<endpoint>/api/v3/compilers?access_token=<access_token>'
package problems;
/**
* Example presents usage of the successful getCompilers() API method
*/
import com.SphereEngine.Api.ProblemsClientV3;
import com.SphereEngine.Api.Exception.NotAuthorizedException;
import com.SphereEngine.Api.Exception.ClientException;
import com.SphereEngine.Api.Exception.ConnectionException;
import com.google.gson.JsonObject;
public class getCompilers
{
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");
} catch (ClientException e) {
System.out.println(e.getMessage());
} catch (ConnectionException e) {
System.out.println(e.getMessage());
}
}
}
<?php
/**
* Example presents usage of the successful getCompilers() API method
*/
use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;
// require library
require_once('../../../vendor/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');
// define access parameters
var accessToken = '<access_token>';
var endpoint = '<endpoint>';
// send request
request({
url: 'https://' + endpoint + '/api/v3/compilers?access_token=' + accessToken,
method: 'GET'
}, function (error, response, body) {
if (error) {
console.log('Connection problem');
}
// process response
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) {
// define access parameters
string endpoint = "<endpoint>";
string accessToken = "<access_token>";
try {
WebClient client = new WebClient();
// send request
byte[] responseBytes = client.DownloadData("https://" + endpoint + "/api/v3/compilers?access_token=" + accessToken);
string responseBody = Encoding.UTF8.GetString(responseBytes);
// process response
Console.WriteLine(responseBody);
} catch (WebException exception) {
WebResponse response = exception.Response;
HttpStatusCode statusCode = (((HttpWebResponse) response).StatusCode);
// fetch errors
if (statusCode == HttpStatusCode.Unauthorized) {
Console.WriteLine("Invalid access token");
}
response.Close();
}
}
}
}
require 'net/http'
require 'uri'
require 'json'
# define access parameters
endpoint = "<endpoint>"
access_token = "<access_token>"
# send request
uri = URI.parse("https://" + endpoint + "/api/v3/compilers?access_token=" + access_token)
http = Net::HTTP.new(uri.host, uri.port)
begin
response = http.request(Net::HTTP::Get.new(uri.request_uri))
# process response
case response
when Net::HTTPSuccess
puts JSON.parse(response.body)
when Net::HTTPUnauthorized
puts "Invalid access token"
end
rescue => e
puts "Connection error"
end
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",
"highlightjs": "cpp",
"prism": "cpp",
"monaco": "cpp",
"code_prettify": "cpp"
},
{
"id": 116,
"name": "Python 3",
"ver": "3.5",
"short": "PYTHON3",
"ace": "python",
"geshi": "python",
"pygments": "python",
"highlights": "python",
"rouge": "python",
"codemirror": "python",
"highlightjs": "python",
"prism": "python",
"monaco": "python",
"code_prettify": "python"
}
]
}
Returns information about a submission.
Request parameters
Name | Located in | Type | Description |
---|---|---|---|
access_token |
query | string | access token |
id |
path | string | 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 |
Examples
curl -X GET -H 'Content-Type: application/json' 'https://<endpoint>/api/v3/submissions/:id?access_token=<access_token>'
package problems.submissions;
/**
* Example presents error handling for getSubmission() API method
*/
import com.SphereEngine.Api.ProblemsClientV3;
import com.SphereEngine.Api.Exception.NotAuthorizedException;
import com.SphereEngine.Api.Exception.NotFoundException;
import com.SphereEngine.Api.Exception.ClientException;
import com.SphereEngine.Api.Exception.ConnectionException;
import com.google.gson.JsonObject;
public class getSubmission
{
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");
} catch (ClientException e) {
System.out.println(e.getMessage());
} catch (ConnectionException e) {
System.out.println(e.getMessage());
}
}
}
<?php
/**
* Example presents error handling for getSubmission() API method
*/
use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;
// require library
require_once('../../../../vendor/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');
// define access parameters
var accessToken = '<access_token>';
var endpoint = '<endpoint>';
// define request parameters
var submissionId = 2016;
// send request
request({
url: 'https://' + endpoint + '/api/v3/submissions/' + submissionId + '?access_token=' + accessToken,
method: 'GET'
}, function (error, response, body) {
if (error) {
console.log('Connection problem');
}
// process response
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) {
// define access parameters
string endpoint = "<endpoint>";
string accessToken = "<access_token>";
// define request parameters
int submissionId = 2016;
try {
WebClient client = new WebClient();
// send request
byte[] responseBytes = client.DownloadData("https://" + endpoint + "/api/v3/submissions/" + submissionId + "?access_token=" + accessToken);
string responseBody = Encoding.UTF8.GetString(responseBytes);
// process response
Console.WriteLine(responseBody);
} catch (WebException exception) {
WebResponse response = exception.Response;
HttpStatusCode statusCode = (((HttpWebResponse) response).StatusCode);
// fetch errors
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();
}
}
}
}
require 'net/http'
require 'uri'
require 'json'
# define access parameters
endpoint = "<endpoint>"
access_token = "<access_token>"
# define request parameters
submission_id = "2016"
# send request
uri = URI.parse("https://" + endpoint + "/api/v3/submissions/" + submission_id + "?access_token=" + access_token)
http = Net::HTTP.new(uri.host, uri.port)
begin
response = http.request(Net::HTTP::Get.new(uri.request_uri))
# process response
case response
when Net::HTTPSuccess
puts JSON.parse(response.body)
when Net::HTTPUnauthorized
puts "Invalid access token"
when Net::HTTPForbidden
puts "Access denied"
when Net::HTTPNotFound
puts "Submission not found"
end
rescue => e
puts "Connection error"
end
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": "https://<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
}
]
}
}
Creates a new submission. Note that every usage of this method decreases submissions pool for your account.
If you want to create a submission with many files see: multi-file mode.
Request parameters
Name | Located in | Type | Description |
---|---|---|---|
access_token |
query | string | access token |
problemCode |
formData | string | problem code |
source |
formData | string | source code (see also: multi-file mode) |
compilerId |
formData | integer | compiler id |
userId | formData | integer | 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 |
Examples
$ cat request.json
{
"problemCode": "SETEST",
"compilerId": 1,
"source": "<source code>"
}
$ curl -X POST -H 'Content-Type: application/json' -d "`cat request.json`" 'https://<endpoint>/api/v3/submissions?access_token=<access_token>'
package problems.submissions;
/**
* Example presents error handling for createSubmission() API method
*/
import com.SphereEngine.Api.ProblemsClientV3;
import com.SphereEngine.Api.Exception.NotAuthorizedException;
import com.SphereEngine.Api.Exception.NotFoundException;
import com.SphereEngine.Api.Exception.BadRequestException;
import com.SphereEngine.Api.Exception.ClientException;
import com.SphereEngine.Api.Exception.ConnectionException;
import com.google.gson.JsonObject;
public class createSubmission
{
public static void main(String[] args)
{
ProblemsClientV3 client = new ProblemsClientV3(
"<access_token>",
"<endpoint>");
String problemCode = "TEST";
String source = "<source code>";
Integer compiler = 11; // C language
try {
JsonObject response = client.createSubmission(problemCode, source, compiler);
} 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");
} catch (ClientException e) {
System.out.println(e.getMessage());
} catch (ConnectionException e) {
System.out.println(e.getMessage());
}
}
}
<?php
/**
* Example presents error handling for createSubmission() API method
*/
use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;
// require library
require_once('../../../../vendor/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');
// define access parameters
var accessToken = '<access_token>';
var endpoint = '<endpoint>';
// define request parameters
var submissionData = {
problemCode: 'EXAMPLE',
compilerId: 11,
source: '<source_code>'
};
// send request
request({
url: 'https://' + endpoint + '/api/v3/submissions?access_token=' + accessToken,
method: 'POST',
form: submissionData
}, function (error, response, body) {
if (error) {
console.log('Connection problem');
}
// process response
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) {
// define access parameters
string endpoint = "<endpoint>";
string accessToken = "<access_token>";
try {
WebClient client = new WebClient ();
// define request parameters
NameValueCollection formData = new NameValueCollection ();
formData.Add("problemCode", "EXAMPLE");
formData.Add("source", "<source_code>");
formData.Add("compilerId", "11");
// send request
byte[] responseBytes = client.UploadValues ("https://" + endpoint + "/api/v3/submissions?access_token=" + accessToken, "POST", formData);
string responseBody = Encoding.UTF8.GetString(responseBytes);
// process response
Console.WriteLine(responseBody);
} catch (WebException exception) {
WebResponse response = exception.Response;
HttpStatusCode statusCode = (((HttpWebResponse)response).StatusCode);
// fetch errors
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();
}
}
}
}
require 'net/http'
require 'uri'
require 'json'
# define access parameters
endpoint = "<endpoint>"
access_token = "<access_token>"
# define request parameters
submission_data = {
"problemCode" => 'EXAMPLE',
"compilerId" => "11",
"source" => '<source_code>'
};
# send request
uri = URI.parse("https://" + endpoint + "/api/v3/submissions?access_token=" + access_token)
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.request_uri);
request.set_form_data(submission_data)
begin
response = http.request(request)
# process response
case response
when Net::HTTPCreated
puts JSON.parse(response.body)
when Net::HTTPUnauthorized
puts "Invalid access token"
when Net::HTTPBadRequest
puts "Empty source code"
when Net::HTTPForbidden
puts "Compiler not available"
when Net::HTTPNotFound
puts "Problem, compiler or user not found"
end
rescue => e
puts "Connection error"
end
Response example
{
"id": 42
}
Returns information about submissions. Results are sorted ascending by id.
Request parameters
Name | Located in | Type | Description |
---|---|---|---|
access_token |
query | string | access token |
ids |
query | string | 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 |
Examples
curl -X GET -H 'Content-Type: application/json' 'https://<endpoint>/api/v3/submissions?ids=:ids&access_token=<access_token>'
package problems.submissions;
/**
* Example presents error handling for getSubmissions() API method
*/
import com.SphereEngine.Api.ProblemsClientV3;
import com.SphereEngine.Api.Exception.NotAuthorizedException;
import com.SphereEngine.Api.Exception.ClientException;
import com.SphereEngine.Api.Exception.ConnectionException;
import com.google.gson.JsonObject;
public class getSubmissions
{
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");
} catch (ClientException e) {
System.out.println(e.getMessage());
} catch (ConnectionException e) {
System.out.println(e.getMessage());
}
}
}
<?php
/**
* Example presents error handling for getSubmissions() API method
*/
use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;
// require library
require_once('../../../../vendor/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');
// define access parameters
var accessToken = '<access_token>';
var endpoint = '<endpoint>';
// define request parameters
var submissionsIds = [2016, 2017];
// send request
request({
url: 'https://' + endpoint + '/api/v3/submissions?ids=' + submissionsIds.join() + '&access_token=' + accessToken,
method: 'GET'
}, function (error, response, body) {
if (error) {
console.log('Connection problem');
}
// process response
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');
}
}
}
});
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": "https://<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
}
]
}
}
]
}
Returns the list of problems of the quantity given by limit parameter starting from the offset parameter.
Request parameters
Name | Located in | Type | Description |
---|---|---|---|
access_token |
query | string | access token |
limit | query | integer | limit of problems to get, default: 10, max: 100 |
offset | query | integer | offset, default: 0 |
shortBody | query | boolean | 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 |
Examples
curl -X GET 'https://<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.SphereEngine.Api.Exception.NotAuthorizedException;
import com.SphereEngine.Api.Exception.ClientException;
import com.SphereEngine.Api.Exception.ConnectionException;
import com.google.gson.JsonObject;
public class getProblems
{
public static void main(String[] args)
{
ProblemsClientV3 client = new ProblemsClientV3(
"<access_token>",
"<endpoint>");
try {
JsonObject response = client.getProblems();
} catch (NotAuthorizedException e) {
System.out.println("Invalid access token");
} catch (ClientException e) {
System.out.println(e.getMessage());
} catch (ConnectionException e) {
System.out.println(e.getMessage());
}
}
}
<?php
/**
* Example presents usage of the successful getProblems() API method
*/
use SphereEngine\Api\ProblemsClientV3;
// require library
require_once('../../../../vendor/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');
// define access parameters
var accessToken = '<access_token>';
var endpoint = '<endpoint>';
// send request
request({
url: 'https://' + endpoint + '/api/v3/problems?access_token=' + accessToken,
method: 'GET'
}, function (error, response, body) {
if (error) {
console.log('Connection problem');
}
// process response
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');
}
}
}
});
Response example
{
"items": [
{
"code": "EXPRBL",
"name": "Example Problem",
"lastModifiedBody": 1486478234,
"lastModifiedSettings": 1487929707,
"actions": {
"edit":true,
"clone":true
},
"uri": "https://<endpoint>/api/v3/problems/TEST?access_token=<access_token>"
},
{
"code": "ANOPRBL",
"name": "Another problem",
"lastModifiedBody": 1486491532,
"lastModifiedSettings": 1486496511,
"actions": {
"edit":true,
"clone":true
},
"uri": "https://<endpoint>/api/v3/problems/TEST?access_token=<access_token>"
}
],
"paging": {
"limit": 2,
"offset": 4,
"total": 7,
"pages": 4,
"prev": "https://<endpoint>/api/v3/problems?offset=2&access_token=<access_token>",
"next": "https://<endpoint>/api/v3/problems?offset=6&access_token=<access_token>"
}
}
Creates a new problem
Request parameters
Name | Located in | Type | Description |
---|---|---|---|
access_token |
query | string | access token |
code |
formData | string | problem code |
name |
formData | string | problem name |
body | formData | string | problem body |
type | formData | string | problem type, enum: binary|min|max|pct, default: binary |
interactive | formData | boolean | interactive problem flag, default: 0 |
masterjudgeId | formData | integer | 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 |
Examples
$ cat request.json
{
"code": "<PROBLEMCODE>",
"name": "Name"
}
$ curl -X POST -H 'Content-Type: application/json' -d "`cat request.json`" 'https://<endpoint>/api/v3/problems?access_token=<access_token>'
package problems.problems;
/**
* Example presents usage of the successful createProblem() API method
*/
import com.SphereEngine.Api.ProblemsClientV3;
import com.SphereEngine.Api.Exception.NotAuthorizedException;
import com.SphereEngine.Api.Exception.NotFoundException;
import com.SphereEngine.Api.Exception.BadRequestException;
import com.SphereEngine.Api.Exception.ClientException;
import com.SphereEngine.Api.Exception.ConnectionException;
import com.google.gson.JsonObject;
public class createProblem
{
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());
} catch (ClientException e) {
System.out.println(e.getMessage());
} catch (ConnectionException e) {
System.out.println(e.getMessage());
}
}
}
<?php
/**
* Example presents error handling for createProblem() API method
*/
use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;
// require library
require_once('../../../../vendor/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');
// define access parameters
var accessToken = '<access_token>';
var endpoint = '<endpoint>';
// define request parameters
var problemData = {
name: 'Example',
code: 'EXAMPLE'
};
// send request
request({
url: 'https://' + endpoint + '/api/v3/problems?access_token=' + accessToken,
method: 'POST',
form: problemData
}, function (error, response, body) {
if (error) {
console.log('Connection problem');
}
// process response
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');
}
}
}
});
Response example
{
"code": "PROBLEMCODE"
}
Retrieves an existing problem
Request parameters
Name | Located in | Type | Description |
---|---|---|---|
access_token |
query | string | access token |
code |
path | string | problem code |
shortBody | query | boolean | 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) |
Examples
curl -X GET 'https://<endpoint>/api/v3/problems/:code?access_token=<access_token>'
package problems.problems;
/**
* Example presents usage of the successful getProblem() API method
*/
import com.SphereEngine.Api.ProblemsClientV3;
import com.SphereEngine.Api.Exception.NotAuthorizedException;
import com.SphereEngine.Api.Exception.NotFoundException;
import com.SphereEngine.Api.Exception.ClientException;
import com.SphereEngine.Api.Exception.ConnectionException;
import com.google.gson.JsonObject;
public class getProblem
{
public static void main(String[] args)
{
ProblemsClientV3 client = new ProblemsClientV3(
"<access_token>",
"<endpoint>");
try {
JsonObject response = client.getProblem("TEST");
} catch (NotAuthorizedException e) {
System.out.println("Invalid access token");
} catch (NotFoundException e) {
System.out.println("Problem does not exist");
} catch (ClientException e) {
System.out.println(e.getMessage());
} catch (ConnectionException e) {
System.out.println(e.getMessage());
}
}
}
<?php
/**
* Example presents error handling for getProblem() API method
*/
use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;
// require library
require_once('../../../../vendor/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');
// define access parameters
var accessToken = '<access_token>';
var endpoint = '<endpoint>';
// define request parameters
var problemCode = 'EXAMPLE';
// send request
request({
url: 'https://' + endpoint + '/api/v3/problems/' + problemCode + '?access_token=' + accessToken,
method: 'GET'
}, function (error, response, body) {
if (error) {
console.log('Connection problem');
}
// process response
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');
}
}
}
});
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": "https://<endpoint>/judges/1001?access_token=<access_token>"
},
"testcases": [
{
"number": 0,
"active": true
},
{
"number": 1,
"active": false
}
],
"lastModifiedBody": 1486478234,
"lastModifiedSettings": 1487929707
}
Updates an existing problem
Request parameters
Name | Located in | Type | Description |
---|---|---|---|
access_token |
query | string | access token |
code |
path | string | problem code |
name | formData | string | problem name |
body | formData | string | problem body |
type | formData | string | problem type, enum: binary|min|max|pct, default: binary |
interactive | formData | boolean | interactive problem flag |
masterjudgeId | formData | integer | master judge id |
activeTestcases | formData | string | 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 |
Examples
$ cat request.json
{
"name": "<new_name>"
}
$ curl -X PUT -H 'Content-Type: application/json' -d "`cat request.json`" 'https://<endpoint>/api/v3/problems/:code?access_token=<access_token>'
package problems.problems;
/**
* Example presents usage of the successful updateProblem() API method
*/
import com.SphereEngine.Api.ProblemsClientV3;
import com.SphereEngine.Api.Exception.NotAuthorizedException;
import com.SphereEngine.Api.Exception.NotFoundException;
import com.SphereEngine.Api.Exception.ForbiddenException;
import com.SphereEngine.Api.Exception.BadRequestException;
import com.SphereEngine.Api.Exception.ClientException;
import com.SphereEngine.Api.Exception.ConnectionException;
import com.google.gson.JsonObject;
public class updateProblem
{
public static void main(String[] args)
{
ProblemsClientV3 client = new ProblemsClientV3(
"<access_token>",
"<endpoint>");
String newProblemName = "New example problem name";
try {
JsonObject response = client.updateProblem("EXAMPLE", 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());
} catch (ClientException e) {
System.out.println(e.getMessage());
} catch (ConnectionException e) {
System.out.println(e.getMessage());
}
}
}
<?php
/**
* Example presents error handling for updateProblem() API method
*/
use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;
// require library
require_once('../../../../vendor/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');
// define access parameters
var accessToken = '<access_token>';
var endpoint = '<endpoint>';
// define request parameters
var problemCode = 'EXAMPLE';
var problemData = {
name: 'New name'
};
// send request
request({
url: 'https://' + endpoint + '/api/v3/problems/' + problemCode + '?access_token=' + accessToken,
method: 'PUT',
form: problemData
}, function (error, response, body) {
if (error) {
console.log('Connection problem');
}
// process response
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');
}
}
}
});
Response example
{}
Retrieves list of problem test cases
Request parameters
Name | Located in | Type | Description |
---|---|---|---|
access_token |
query | string | access token |
code |
path | string | 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 |
Examples
curl -X GET 'https://<endpoint>/api/v3/problems/:code/testcases?access_token=<access_token>'
package problems.problems;
/**
* Example presents usage of the successful getProblemTestcases() API method
*/
import com.SphereEngine.Api.ProblemsClientV3;
import com.SphereEngine.Api.Exception.NotAuthorizedException;
import com.SphereEngine.Api.Exception.NotFoundException;
import com.SphereEngine.Api.Exception.ForbiddenException;
import com.SphereEngine.Api.Exception.ClientException;
import com.SphereEngine.Api.Exception.ConnectionException;
import com.google.gson.JsonObject;
public class getProblemTestcases
{
public static void main(String[] args)
{
ProblemsClientV3 client = new ProblemsClientV3(
"<access_token>",
"<endpoint>");
try {
JsonObject response = client.getProblemTestcases("TEST");
} 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");
} catch (ClientException e) {
System.out.println(e.getMessage());
} catch (ConnectionException e) {
System.out.println(e.getMessage());
}
}
}
<?php
/**
* Example presents error handling for getProblemTestcases() API method
*/
use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;
// require library
require_once('../../../../vendor/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');
// define access parameters
var accessToken = '<access_token>';
var endpoint = '<endpoint>';
// define request parameters
var problemCode = 'EXAMPLE';
// send request
request({
url: 'https://' + endpoint + '/api/v3/problems/' + problemCode + '/testcases?access_token=' + accessToken,
method: 'GET'
}, function (error, response, body) {
if (error) {
console.log('Connection problem');
}
// process response
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');
}
}
}
});
Response example
{
"testcases": [
{
"number": 0,
"active": true,
"input": {
"size": 7,
"uri":"https://<endpoint>/api/v3/problems/EXPRBL/testcases/0/input-EXPRBL-0.txt?access_token=<access_token>"
},
"output": {
"size": 9,
"uri":"https://<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": "https://<endpoint>/api/v3/judges/1?access_token=<access_token>"
}
},
{
"number": 1,
"active": false,
"input": {
"size": 3,
"uri":"https://<endpoint>/api/v3/problems/EXPRBL/testcases/1/input-EXPRBL-1.txt?access_token=<access_token>"
},
"output": {
"size": 2,
"uri":"https://<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": "https://<endpoint>/api/v3/judges/1?access_token=<access_token>"
}
}
]
}
Creates a problem test case
Request parameters
Name | Located in | Type | Description |
---|---|---|---|
access_token |
query | string | access token |
code |
path | string | problem code |
input | formData | string | input data, default: empty |
output | formData | string | output data, default: empty |
timelimit | formData | float | time limit in seconds, default: 1 |
judgeId | formData | integer | judge id, default: 1 (Ignore extra whitespaces) |
active | formData | boolean | 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 |
Examples
$ cat request.json
{
"input": "input content",
"timelimit": 10,
"output": "output content"
}
$ curl -X POST -H 'Content-Type: application/json' -d "`cat request.json`" 'https://<endpoint>/api/v3/problems/:code/testcases?access_token=<access_token>'
package problems.problems;
/**
* Example presents usage of the successful createProblemTestcase() API method
*/
import com.SphereEngine.Api.ProblemsClientV3;
import com.SphereEngine.Api.Exception.NotAuthorizedException;
import com.SphereEngine.Api.Exception.NotFoundException;
import com.SphereEngine.Api.Exception.ForbiddenException;
import com.SphereEngine.Api.Exception.ClientException;
import com.SphereEngine.Api.Exception.ConnectionException;
import com.google.gson.JsonObject;
public class createProblemTestcase
{
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 judgeId = 1;
try {
JsonObject response = client.createProblemTestcase(code, input, output, timelimit, judgeId);
// 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());
} catch (ClientException e) {
System.out.println(e.getMessage());
} catch (ConnectionException e) {
System.out.println(e.getMessage());
}
}
}
<?php
/**
* Example presents error handling for createProblemTestcase() API method
*/
use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;
// require library
require_once('../../../../vendor/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');
// define access parameters
var accessToken = '<access_token>';
var endpoint = '<endpoint>';
// define request parameters
var problemCode = 'EXAMPLE';
var testcaseData = {
input: 'Input',
output: 'Output',
timelimit: 5,
judgeId: 1
};
// send request
request({
url: 'https://' + endpoint + '/api/v3/problems/' + problemCode + '/testcases?access_token=' + accessToken,
method: 'POST',
form: testcaseData
}, function (error, response, body) {
if (error) {
console.log('Connection problem');
}
// process response
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 ');
}
}
}
});
Response example
{
"number": 3
}
Retrieves problem test case
Request parameters
Name | Located in | Type | Description |
---|---|---|---|
access_token |
query | string | access token |
code |
path | string | problem code |
number |
path | integer | 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 |
Examples
curl -X GET 'https://<endpoint>/api/v3/problems/:code/testcases/:number?access_token=<access_token>'
package problems.problems;
/**
* Example presents usage of the successful getProblemTestcase() API method
*/
import com.SphereEngine.Api.ProblemsClientV3;
import com.SphereEngine.Api.Exception.NotAuthorizedException;
import com.SphereEngine.Api.Exception.NotFoundException;
import com.SphereEngine.Api.Exception.ForbiddenException;
import com.SphereEngine.Api.Exception.ClientException;
import com.SphereEngine.Api.Exception.ConnectionException;
import com.google.gson.JsonObject;
public class getProblemTestcase
{
public static void main(String[] args)
{
ProblemsClientV3 client = new ProblemsClientV3(
"<access_token>",
"<endpoint>");
String problemCode = "TEST";
Integer testcaseNumber = 0;
try {
JsonObject response = client.getProblemTestcase(problemCode, testcaseNumber);
} 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());
} catch (ClientException e) {
System.out.println(e.getMessage());
} catch (ConnectionException e) {
System.out.println(e.getMessage());
}
}
}
<?php
/**
* Example presents error handling for getProblemTestcase() API method
*/
use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;
// require library
require_once('../../../../vendor/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');
// define access parameters
var accessToken = '<access_token>';
var endpoint = '<endpoint>';
// define request parameters
var problemCode = 'EXAMPLE';
var testcaseNumber = 0;
// send request
request({
url: 'https://' + endpoint + '/api/v3/problems/' + problemCode + '/testcases/' + testcaseNumber + '?access_token=' + accessToken,
method: 'GET'
}, function (error, response, body) {
if (error) {
console.log('Connection problem');
}
// process response
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');
}
}
}
});
Response example
{
"number": 0,
"active": true,
"input": {
"size":7,
"uri":"https://<endpoint>/api/v3/problems/EXPRBL/testcases/0/input-EXPRBL-0.txt?access_token=<access_token>"
},
"output":{
"size":9,
"uri":"https://<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": "https://<endpoint>/api/v3/judges/1?access_token=<access_token>"
}
}
Updates the problem test case
Request parameters
Name | Located in | Type | Description |
---|---|---|---|
access_token |
query | string | access token |
code |
path | string | problem code |
number |
path | integer | test case number |
input | formData | string | input data |
output | formData | string | output data |
timelimit | formData | float | time limit in seconds |
judgeId | formData | integer | 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 |
Examples
$ cat request.json
{
"input": "updated content",
"timelimit": 9,
"output": "updated content"
}
$ curl -X PUT -H 'Content-Type: application/json' -d "`cat request.json`" 'https://<endpoint>/api/v3/problems/:code/testcases/:number?access_token=<access_token>'
package problems.problems;
/**
* Example presents usage of the successful updateProblemTestcase() API method
*/
import com.SphereEngine.Api.ProblemsClientV3;
import com.SphereEngine.Api.Exception.NotAuthorizedException;
import com.SphereEngine.Api.Exception.NotFoundException;
import com.SphereEngine.Api.Exception.ForbiddenException;
import com.SphereEngine.Api.Exception.ClientException;
import com.SphereEngine.Api.Exception.ConnectionException;
import com.google.gson.JsonObject;
public class updateProblemTestcase
{
public static void main(String[] args)
{
ProblemsClientV3 client = new ProblemsClientV3(
"<access_token>",
"<endpoint>");
String problemCode = "TEST";
Integer testcaseNumber = 0;
String newInput = "New testcase input";
try {
JsonObject response = client.updateProblemTestcase(problemCode, testcaseNumber, newInput);
} 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());
} catch (ClientException e) {
System.out.println(e.getMessage());
} catch (ConnectionException e) {
System.out.println(e.getMessage());
}
}
}
<?php
/**
* Example presents error handling for updateProblemTestcase() API method
*/
use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;
// require library
require_once('../../../../vendor/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');
// define access parameters
var accessToken = '<access_token>';
var endpoint = '<endpoint>';
// define request parameters
var problemCode = 'EXAMPLE';
var testcaseNumber = 0;
var testcaseData = {
input: 'New input'
};
// send request
request({
url: 'https://' + endpoint + '/api/v3/problems/' + problemCode + '/testcases/' + testcaseNumber + '?access_token=' + accessToken,
method: 'PUT',
form: testcaseData
}, function (error, response, body) {
if (error) {
console.log('Connection problem');
}
// process response
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');
}
}
}
});
Response example
{}
Retrieves Problem test case file
Request parameters
Name | Located in | Type | Description |
---|---|---|---|
access_token |
query | string | access token |
code |
path | string | problem code |
number |
path | integer | test case number |
filename |
path | string | stream name |
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 |
Examples
curl -X GET 'https://<endpoint>/api/v3/problems/:code/testcases/:number/:filename?access_token=<access_token>'
package problems.problems;
/**
* Example presents usage of the successful getProblemTestcaseFile() API method
*/
import com.SphereEngine.Api.ProblemsClientV3;
import com.SphereEngine.Api.Exception.NotAuthorizedException;
import com.SphereEngine.Api.Exception.NotFoundException;
import com.SphereEngine.Api.Exception.ForbiddenException;
import com.SphereEngine.Api.Exception.ClientException;
import com.SphereEngine.Api.Exception.ConnectionException;
public class getProblemTestcaseFile
{
public static void main(String[] args)
{
ProblemsClientV3 client = new ProblemsClientV3(
"<access_token>",
"<endpoint>");
String problemCode = "TEST";
Integer testcaseNumber = 0;
String file = "input";
try {
String response = client.getProblemTestcaseFile(problemCode, testcaseNumber, file);
} 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());
} catch (ClientException e) {
System.out.println(e.getMessage());
} catch (ConnectionException e) {
System.out.println(e.getMessage());
}
}
}
<?php
/**
* Example presents error handling for getProblemTestcaseFile() API method
*/
use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;
// require library
require_once('../../../../vendor/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');
// define access parameters
var accessToken = '<access_token>';
var endpoint = '<endpoint>';
// define request parameters
var problemCode = 'EXAMPLE';
var testcaseNumber = 0;
var fileName = '<file_name>'
// send request
request({
url: 'https://' + endpoint + '/api/v3/problems/' + problemCode + '/testcases/' + testcaseNumber + '/' + fileName + '?access_token=' + accessToken,
method: 'GET'
}, function (error, response, body) {
if (error) {
console.log('Connection problem');
}
// process response
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');
}
}
}
});
Response example
Raw data from selected file.
Returns the list of judges of the quantity given by limit parameter starting from the offset parameter.
Request parameters
Name | Located in | Type | Description |
---|---|---|---|
access_token |
query | string | access token |
limit | query | integer | limit of judges to get, default: 10, max: 100 |
offset | query | integer | offset, default: 0 |
type | query | string | 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 |
Examples
curl -X GET 'https://<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.SphereEngine.Api.Exception.ClientException;
import com.SphereEngine.Api.Exception.ConnectionException;
import com.google.gson.JsonObject;
public class getJudges
{
public static void main(String[] args)
{
ProblemsClientV3 client = new ProblemsClientV3(
"<access_token>",
"<endpoint>");
try {
JsonObject response = client.getJudges();
} catch (ClientException e) {
System.out.println(e.getMessage());
} catch (ConnectionException e) {
System.out.println(e.getMessage());
}
}
}
<?php
/**
* Example presents usage of the successful getJudges() API method
*/
use SphereEngine\Api\ProblemsClientV3;
// require library
require_once('../../../../vendor/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');
// define access parameters
var accessToken = '<access_token>';
var endpoint = '<endpoint>';
// send request
request({
url: 'https://' + endpoint + '/api/v3/judges?access_token=' + accessToken,
method: 'GET'
}, function (error, response, body) {
if (error) {
console.log('Connection problem');
}
// process response
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');
}
}
}
});
Response example
{
"items": [
{
"id": 1,
"name": "Ignores extra whitespaces",
"uri": "https://<endpoint>/api/v3/judges/1?access_token=<access_token>",
"type": "testcase"
},
{
"id": 2,
"name":"Ignores FP rounding up to 10^-2",
"uri": "https://<endpoint>/api/v3/judges/2?access_token=<access_token>",
"type": "testcase"
}
],
"paging": {
"limit": 2,
"offset": 4,
"total": 9,
"pages": 5,
"prev": "https://<endpoint>/api/v3/judges?offset=2&access_token=<access_token>",
"next": "https://<endpoint>/api/v3/judges?offset=6&access_token=<access_token>"
}
}
Creates a new judge
Request parameters
Name | Located in | Type | Description |
---|---|---|---|
access_token |
query | string | access token |
name | formData | string | judge name, default: empty |
type | formData | string | judge type, testcase|master, default: testcase |
compilerId | formData | integer | compiler id, default: 1 (C++) |
source |
formData | string | 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 |
Examples
$ cat request.json
{
"source": "<source code>"
}
$ curl -X POST -H 'Content-Type: application/json' -d "`cat request.json`" 'https://<endpoint>/api/v3/judges?access_token=<access_token>'
package problems.judges;
/**
* Example presents usage of the successful createJudge() API method
*/
import com.SphereEngine.Api.ProblemsClientV3;
import com.SphereEngine.Api.Exception.NotAuthorizedException;
import com.SphereEngine.Api.Exception.NotFoundException;
import com.SphereEngine.Api.Exception.BadRequestException;
import com.SphereEngine.Api.Exception.ClientException;
import com.SphereEngine.Api.Exception.ConnectionException;
import com.google.gson.JsonObject;
public class createJudge
{
public static void main(String[] args)
{
ProblemsClientV3 client = new ProblemsClientV3(
"<access_token>",
"<endpoint>");
String source = "<source code>";
Integer compiler = 11; // C language
try {
JsonObject response = client.createJudge(source, compiler);
// 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");
} catch (ClientException e) {
System.out.println(e.getMessage());
} catch (ConnectionException e) {
System.out.println(e.getMessage());
}
}
}
<?php
/**
* Example presents error handling for createJudge() API method
*/
use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;
// require library
require_once('../../../../vendor/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');
// define access parameters
var accessToken = '<access_token>';
var endpoint = '<endpoint>';
// define request parameters
var judgeData = {
compilerId: 11,
source: '<source_code>'
};
// send request
request({
url: 'https://' + endpoint + '/api/v3/judges?access_token=' + accessToken,
method: 'POST',
form: judgeData
}, function (error, response, body) {
if (error) {
console.log('Connection problem');
}
// process response
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');
}
}
}
});
Response example
{
"id": 42
}
Retrieves an existing judge
Request parameters
Name | Located in | Type | Description |
---|---|---|---|
access_token |
query | string | access token |
id |
path | integer | 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 |
Examples
curl -X GET 'https://<endpoint>/api/v3/judges/:id?access_token=<access_token>'
package problems.judges;
/**
* Example presents usage of the successful getJudge() API method
*/
import com.SphereEngine.Api.ProblemsClientV3;
import com.SphereEngine.Api.Exception.NotAuthorizedException;
import com.SphereEngine.Api.Exception.NotFoundException;
import com.SphereEngine.Api.Exception.ForbiddenException;
import com.SphereEngine.Api.Exception.ClientException;
import com.SphereEngine.Api.Exception.ConnectionException;
import com.google.gson.JsonObject;
public class getJudge
{
public static void main(String[] args)
{
ProblemsClientV3 client = new ProblemsClientV3(
"<access_token>",
"<endpoint>");
try {
JsonObject response = client.getJudge(1);
} 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");
} catch (ClientException e) {
System.out.println(e.getMessage());
} catch (ConnectionException e) {
System.out.println(e.getMessage());
}
}
}
<?php
/**
* Example presents error handling for getJudge() API method
*/
use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;
// require library
require_once('../../../../vendor/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');
// define access parameters
var accessToken = '<access_token>';
var endpoint = '<endpoint>';
// define request parameters
var judgeId = 1;
// send request
request({
url: 'https://' + endpoint + '/api/v3/judges/' + judgeId + '?access_token=' + accessToken,
method: 'GET'
}, function (error, response, body) {
if (error) {
console.log('Connection problem');
}
// process response
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('Judge not found');
}
}
}
});
Response example
{
"id": 1,
"name": "Ignores extra whitespaces",
"source": "judge source code",
"compiler": {
"id": 1,
"name": "C++"
},
"type": "testcase"
}
Updates an existing judge
Request parameters
Name | Located in | Type | Description |
---|---|---|---|
access_token |
query | string | access token |
id |
path | integer | judge id |
name | formData | string | judge name |
compilerId | formData | integer | compiler id |
source | formData | string | 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 |
Examples
$ cat request.json
{
"name": "<new_name>"
}
$ curl -X PUT -H 'Content-Type: application/json' -d "`cat request.json`" 'https://<endpoint>/api/v3/judges/:id?access_token=<access_token>'
package problems.judges;
/**
* Example presents usage of the successful updateJudge() API method
*/
import com.SphereEngine.Api.ProblemsClientV3;
import com.SphereEngine.Api.Exception.NotAuthorizedException;
import com.SphereEngine.Api.Exception.NotFoundException;
import com.SphereEngine.Api.Exception.ForbiddenException;
import com.SphereEngine.Api.Exception.BadRequestException;
import com.SphereEngine.Api.Exception.ClientException;
import com.SphereEngine.Api.Exception.ConnectionException;
import com.google.gson.JsonObject;
public class updateJudge
{
public static void main(String[] args)
{
ProblemsClientV3 client = new ProblemsClientV3(
"<access_token>",
"<endpoint>");
String source = "<source code>";
Integer compiler = 11; // C language
try {
JsonObject response = client.updateJudge(1, source, compiler);
} 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");
} catch (ClientException e) {
System.out.println(e.getMessage());
} catch (ConnectionException e) {
System.out.println(e.getMessage());
}
}
}
<?php
/**
* Example presents error handling for updateJudge() API method
*/
use SphereEngine\Api\ProblemsClientV3;
use SphereEngine\Api\SphereEngineResponseException;
// require library
require_once('../../../../vendor/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');
// define access parameters
var accessToken = '<access_token>';
var endpoint = '<endpoint>';
// define request parameters
var judgeId = 1;
var judgeData = {
compilerId: 11,
source: '<source_code>'
};
// send request
request({
url: 'https://' + endpoint + '/api/v3/judges/' + judgeId + '?access_token=' + accessToken,
method: 'PUT',
form: judgeData
}, function (error, response, body) {
if (error) {
console.log('Connection problem');
}
// process response
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');
}
}
}
});
Response example
{}