API Changelog

The following article summarizes the changes made to Sphere Engine API.

API v1.1 for Containers module

Along with the introduction of the Sphere Engine Containers module, we introduced a new API. It is as consistent as possible with the existing API V4 for the Compilers and the Problems modules.

For more information refer to:

API v4 vs API v3 for Compilers and Problems module

The following section summarizes changes between the 3^rd and 4^th versions of Sphere Engine API. Among numerous new features, functional and performance improvements, and bug fixes there are many changes in the API interface, for example:

new methods, parameters, and fields in responses,
unification in naming and structure,
better semantic data grouping in responses,
removal of deprecated methods, parameters, and fields in responses.

The list of changes is designed to be a convenient source of information during the migration process.

Common for Compilers and Problems API

Added

added support for multi-file submissions (see multi-file mode),
added support for disk operations in submitted programs (see disk operations),
added support for multiple versions of languages (e.g., C++ (gcc 5.1), C++ (gcc 6.3)),
added extended error codes (field error_code) to API responses in case of errors; this change makes it possible to precisely identify errors,
added multiple new error types in various API methods,
added new fields in parameters related to multiple versions of languages in various methods (in both parameters and field in responses),
added information about languages versions to the response of GET /compilers method response,
added new field executing to the submission details in GET /submissions/:id and GET /submissions methods responses,
added new field result.streams to the submission details in GET /submissions/:id method response,
added new field uri to the submission details in GET /submissions method response,
added new parameters compilerVersionId, files to POST /submissions method.

Changed

unified naming standard for data streams (stdin -> input, stdout -> output, stderr -> error, cmperr -> cmpinfo, psinfo -> debug) in various methods,
modified structure of GET /compilers method response,
significant changes in the structure of GET /submissions/:id and GET /submissions methods responses,
data that is not yet available to be retrieved is presently shown as null in method responses (e.g., while the submission is in the middle of processing there is no information about execution time, thus, returned value is null; previously in such cases 0 was returned).

Removed

removed submission streams data (i.e., source, input, output, error, cmpinfo, debug) from the GET /submissions/:id method response; this change eliminates potential issues with binary data in streams,
removed default values for compilerId and source parameters from POST /submissions; both parameters are now required.

Compilers API

Added

added support for output-files (see output files),
added new parameters timeLimit, memoryLimit to POST /submissions method.

Changed

api endpoint is now {customer_key}.compilers.sphere-engine.com instead of its former version ~~{customer_key}.api.compilers.sphere-engine.com~~ for consistency with Problems API,
modified structure of GET /test method response to be consistent with the same method in Problems API,
format of date in GET /submissions/:id and GET /submissions methods responses is now YYYY-MM-DD hh:mm:ss +Z instead of YYYY-MM-DD hh:mm:ss (i.e., information about time zone is added),
integer-type field status in submission details in GET /submissions and GET /submissions/:id methods responses has been replaced with complex-type structure with two fields, i.e., result.status.code and result.status.name,
values from field result are merged with values from status field in submission details in GET /submissions and GET /submissions/:id methods responses; the merged value is stored in field result.status.code.

Removed

removed field error from responses of all methods,
removed deprecated GET /languages that was redundant due to existence of GET /compilers method,
removed deprecated field langId, langName, langVersion, public and compiler.ver in submission details in GET /submission/:id and GET /submissions methods responses,
removed field output_type from GET /submission/:id method response,
removed field result from GET /submission/:id method response in its former interpretation; currently, present result field aggregates all data generated during runtime of the program,
removed parameters withSource, withInput, withOutput, withStderr and withCmpinfo from GET /submission/:id method,
removed deprecated sourceCode and compiler parameters from POST /submissions method.

Problems API

Added

added method GET /submissions/:id/:stream for retrieving data from submission streams (i.e., source, output, error, cmpinfo, debug),
added optional parameter tests to method POST /submissions; this parameter allows selecting of test cases for which a submission will be tested,
added new field id to POST /problems method response,
added new field id to problem details in GET /problems and GET /problems/:id methods responses,
added method DELETE /problems/:id for removing programming problems,
added new field uri to the test case details in GET /problems/:code/testcases method response,
added new field data to GET /problems/:code/testcases/:number method response,
added new field visibility to judge details in GET /judges and GET /judges/:id methods responses,
added new field compiler.version to GET /judges/:id method response,
added method GET /judges/:id/:filename for retrieving judge files,
added new parameter shared to POST /judges method response,
added new parameter shared to PUT /judges method response.

Changed

the "code" of the programming problem has been replaced with the "id" of the integer type; this change affects various methods that were previously based on the "code"; it is still possible to use the "code", however, it is deprecated; new integrations should use the "id" as the unique identifier for programming problem,
string-type field status in submission details (and test cases details) in GET /submissions and GET /submissions/:id methods responses has been replaced with a complex-type structure with two fields, i.e., result.status.code and result.status.name (and result.testcases[].status.code, result.testcases[].status.name),
many fields in API responses now have proper type (e.g., result.testcases[].number is now integer, not string),
significant changes in the structure of GET /problems/:id and GET /problems methods responses,
string-type parameter type in POST /problems method has been replaced with int-type typeId parameter; mapping between both parameters is as follows: binary - 0, minimize - 1, maximize - 2,
parameter masterjudgeId in POST /problem method is now required,
fields paging.next and paging.prev are always present in response for GET /problems and GET /judges methods; if there is no previous or next page, then the value of the respective field is equal to null,
field shortBody is always present in problem details in GET /problems and GET /problems/:id methods responses; if the content of the shortBody field was not demanded, then its value is equal to null,
field actions in problem details in GET /problems and GET /problems/:id methods responses has been renamed to permissions,
fields lastModifedBody and lastModifiedSettings in problem details in GET /problems and GET /problems/:id methods responses are reorganized to be lastModified.body and lastModified.settings respectively,
string-type field type in GET /problems/:id method response has been extended to complex-type structure with two fields, i.e., type.id and type.name,
parameter judgeId in POST /problems/:id/testcases is now required,
parameter timelimit in POST /problems/:id/testcases method has been renamed to timeLimit,
field testcases in GET /problems/:code/testcases method response has been renamed to items for consistency with other methods returning collections,
fields input and output in GET /problems/:code/testcases/:number method response are now fields of newly added data field; therefore, these fields are now accessible as data.input and data.output respectively,
string-type field type in judge details in GET /judges and GET /judges/:id methods responses has been extended to a complex-type structure with two fields, i.e., type.id and type.name,
string-type field type in GET /judges/:id method response has been reorganized to a complex-type structure with two fields, i.e., source.size and source.uri,
parameter judgeId in POST /judges is now required,
string-type parameter type in POST /judges method has been replaced with int-type typeId parameter; mapping between both parameters is as follows: testcase - 0, master - 1.

Removed

removed fields source, result.runtime_info from GET /submissions/:id method response,
removed fields result.status_code (and result.testcases.status_code) from submission details (and test cases details) in GET /submissions and GET /submissions/:id method responses,
removed deprecated fields language, result_score, result_time, status, statusDescription, result_memory, result_signal, result_cmperr, result_stdout, result_stderr, result_psinfo and result_array from GET /submissions/:id method response,
removed fields input and output from GET /problems/:code/testcases method response.