Draft 2014 REST interface for source code fetching

From ICPC-Contest Control Standard

Introduction

This page describes a draft interface for fetching contestants' source code, and is intented to be used by e.g. shadow CCS's to obtain a complete state from the main CCS, possibly through a Contest Data Server.

General design principles

The interface is implemented as a HTTP REST interface that outputs information in JSON format. The specific base URL will be dependent on the server (main CCS or CDS) providing the service and will be indicated as baseurl.

Query parameters are passed as variables in the URL instead of encoded in the URL path, e.g.

 GET http://example.com/team?id=10

instead of

 GET http://example.com/team/10

Rationale: this allows for more flexibility to later extend/generalize the interface, e.g. to return results depending on a filter:

 http://example.com/team?group=europe


Interface specification

GET baseurl/submission_files

This provides the file(s) of a specific submission.

Parameters:

  • id required identifier of the submission

Returns a JSON array, with each element an object describing a file, with the following elements:

Name Type Description
filename string filename of this file (without path? any disallowed characters?)
content string base64 encoded contents of the file

To be added: how to encode encode for Java submissions which file contains the main class, and/or what the main class name is?

Rationale

Since additional metadata has to be provided together with the file contents, we use base64 encoding to provide the file within the same JSON output. Otherwise, we'd get multiple different output formats, which require different code to handle.

Example

Request:

 GET http://example.com/submission_files?id=223

Returned data:

 [{"filename":"a.java","content":"<base64_string>"},{"filename":"helper.java","content":"<base64_string>"}]