Documentation

Web services are available to users as an alternative to the visual web interface. Most of the features are only available for instructors, but some services, as the ones for competitions are available to any user.

Services are accessed using http requests (GET, PUT, DELETE), and return (or receive) a YAML document. In this documentation, we use CURL, but other tools may work as well.

All commands will follow this format:

curl [options] https://username:password@jutge.org/services/[address]

Where [options] can be --request DELETE for a DELETE request, -T filename.yml for a PUT request or nothing for a GET request.

Request answers are served by default in YAML, if you want the output in JSON format you can add ?format=json to the end of the request URL. Input format is usally in YAML, JSON currently cannot be used as input.


Courses


Owned Courses

Address: .../courses
Method: GET
Description: Gives information about courses. A YAML document is returned with the following format:

---
own:   #Courses that the user owns
    "Jutge:demo": Demo course with some problems   #The key is "username:coursename" and its value is the course title
    "Jutge:P1": Programació 1
enrolled:   #Courses the user is enrolled to as a student
    "OtherInstructor:other": Other course
public:   #Courses that are public
    "Jutge:P1": Programació 1
    "Jutge:demo": Demo course with some problems

Create/Replace Course

Address: .../courses
Method: PUT
Description: Creates or replaces a course. A YAML document defining the course must be sent. If specified course already exists, it will be replaced, if not it will be created. The YAML document must follow this format:

---
name: Demo   #The name of the course, together with the username of the owner, will identify it (required)
title: Demo course   #The title is the first thing the users will see about the course (required)
description: This is just a demo course.   #A more detailed description about the course.
annotation:   #A private annotation.
public: 1   #Must be 0 or 1. Public means that other instructors will see the course and will be able to copy it.
official: 1   #Only administrators can create official courses. Official means that everybody will be able to join.
lists:   #A list of lists names
    - Demo
documents:   #A list of documents names
    - Demo1
    - Demo2
students:   #A list of the course students emails
    - student1@asdf.com
    - student2@asdf.com
    - student3@asdf.com
tutors:   #A list of the course tutors emails
    - tutor1@asdf.com
    - tutor2@asdf.com

Course Info

Address: .../courses/username:coursename
Method: GET
Description: Gives information about the specified course. Returns a YAML document which follows the same format as the one used to create a course.

Course Problems Info

Address: .../courses/username:coursename/problems
Method: GET
Description:Gives information about the course problems that the students have solved. A YAML document is returned with the following format:

---
owner: Jutge   #Owner of the course
name: demo   #Name of the course
title: Demo course with some problems   #Title of the course
problems_solved:   #A list of the problems solved by each enrolled student
    student1@asdf.com:
        - P17433
        - P37469
    student2@asdf.com:
        - P37469
not_enrolled:   #A list of the students who have not enrolled yet
    - student3@asdf.com
    - student4@asdf.com

Delete Course

Address: .../courses/username:coursename
Method: DELETE
Description: Deletes the specified course.


Lists


Owned Lists

Address: .../lists
Method: GET
Description: Gives information about lists. The YAML document returned will follow this format:

---
own:   #Lists that the user owns
    "Jutge:demo": A demo list with some problems   #The key is "username:listname" and its value is the list title
    "Jutge:all": A demo list with all problems
enrolled:   #Lists that are in a course the user is enrolled to
    "Jutge:demo": A demo list with some problems   #The key is "username:listname" and its value is the list title
    "Jutge:all": A demo list with all problems
    "Instructor:list1": List 1
    "Instructor:list2": List 2
public:   #Lists that are public
    "OtherInstructor:otherlist1": My list 1
    "OtherInstructor:otherlist2": My list 2

Create/Replace List

Address: .../lists
Method: PUT
Description: Creates or replaces a list. A YAML document defining the list must be sent. If specified list already exists, it will be replaced, if not it will be created. The YAML document must follow this format:

---
name: Demo   #The name of the list, together with the username of the owner, will identify it (required)
title: Demo list   #The title is the first thing the users will see about the list (required)
description: This is just a demo list.   #A more detailed description about the list.
annotation:   #A private annotation.
public: 1   #Must be 0 or 1. Public means that other instructors will see the list and will be able to copy it.
official: 1
items:   #A list of items. Can be problem names or headers (starting by !).
    - P68688
    - !This is a header
    - P57548
    - P56118
    - !The next problem will be ignored
    - #P83390

List Info

Address: .../lists/username:listname
Method: GET
Description: Gives information about the specified list. Returns a YAML document which follows the same format as the one used to create a list.


Delete List

Address: .../lists/username:listname
Method: DELETE
Description: Deletes the specified list.


Competitions


Owned Competitions

Address: .../competitions
Method: GET
Description: Returnes a list of the competitions you created. The YAML document will contain the competition identifiers (owner:name) and titles.


Create/Replace Competition

Address: .../competitions
Method: PUT
Description: Creates or replaces a competition. A YAML document defining the competition must be sent. If specified competition already exists, it will be updated, if not it will be created. The YAML document must follow this format:

--- 
name: demo
title: A Demo Competition
description: This is an awesome competition
annotation: My private annotation
course: demo
problem: G00001_en
expected_start: 2014-06-22 12:00 

Competition Info

Address: .../competitions/username:competition_name
Method: GET
Description: Gives information about the specified competition. Returns a YAML document which follows the same format as the one used to create a competition, plus some extra fields with information about its status. No login or permissions are required for this request, but some fields will by only visibile to the competition owner.


Delete Competition

Address: .../competitions/username:competition_name
Method: DELETE
Description: Deletes the specified competitions. Note that you can only delete competitions without any rounds played (you can undo the rounds first).


Participant List

Address: .../competitions/username:competition_name/participants
Method: GET
Description: Retrieves a list of participants in the competition. The YAML document will contain a list of names, emails and player names for each user playing this competition (that is, users that submitted an accepted program before the competition started). No login or permissions are required for this request, but some fields will by only visibile to the competition owner.


Match list

Address: .../competitions/username:competition_name/matches/{round_number}
Method: GET
Description: Returns all the matches for a given round, grouped by turns, and the names of the players in that match. For each played match, it will also contain the final scores and a link to the viewer for that game. No login or permissions are required for this request, but some fields will by only visibile to the competition owner.


Start Competition

Address: .../competitions/username:competition_name/actions/start
Method: PUT
Description: Starts the competition. Once a competition starts, no more participants are allowed to enter it. Note that this won't start the first round.


Start Round

Address: .../competitions/username:competition_name/actions/next
Method: PUT
Description: Starts the next round in the competition.


Delete Round

Address: .../competitions/username:competition_name/actions/undo
Method: PUT
Description: Deletes the last round in the competition. Note that the results will be erased permanently after calling this!


Finish Competition

Address: .../competitions/username:competition_name/actions/finish
Method: PUT
Description: Finishes a competition. No more round can be played when a competition ends.


Exams


Owned Exams

Address: .../exams
Method: GET
Description: Gives information about exams. The YAML document returned will follow this format:

---
own:   #Exams of courses that the user owns
    "Jutge:demo_exam": First Demo Exam
tutor:   #Exams of courses that the user is tutor of
    "Jutge:demo_exam": First Demo Exam
    "Instructor:first_exam": First Exam

New Exam

Address: .../exams
Method: PUT
Description: Creates an exam. A YAML document defining the exam must be sent. If the specified exam already exists an error message will be returned, if not it will be created. The YAML document must follow this format:

---   
name: demo_exam1   #The name of the exam, together with the username of the owner, will identify it (required)
title: First Demo Exam1   #The title is the first thing the users will see about the exam (required)
place: School
description: This is the first demo exam
start: 2010-06-22 12:00   #The expected start time of the exam (required)
running_time: 120   #The length of the exam in minutes (required)
course: demo   #The name of the course the exam belongs to. Must be owned by the user (required)
protection: open   #The exam protection. Options are: open (no code required), samecode (all the students have the same code), random (different code for each student)
compilers:   #Compilers allowed in the exam. Names of the compilers are shown in the left column of the compiler documentation
    - GCC
    - BEEF
contest: 1  #1 if the exam is a contest, 0 if not
problems:   #A list of problems common to all students in the exam.
    - 
      problem: P15243
      caption: P1  #(optional) this will be displayed in addition to the prolem title
      icon: balloons/Pink   #(optional) this indicates the icon of the problem. There is a list of all the available icons in the exam creation page
      weight: 2    #(optional) this is the number of points that the problem will reward to the student
    - 
      problem: P16100
      caption: P2
      icon: numbers/2
      weight: 1
    - 
      problem: P19724
      caption: P3
      icon: balloons/BlueViolet
      weight: 1
    - 
      problem: P31675
      caption: P4
      icon: pokemon/abra
      weight: 1
    - 
      problem: P31111
      caption: P5
      icon: summer/beach-ball
      weight: 1
    - 
      problem: P34755
      caption: P6
      icon: candies/candy-corn
      weight: 1
    - 
      problem: P37500
      caption: P7
      icon: essential/app
      weight: 1
    - 
      problem: P41641
      caption: P8
      icon: letters-arial/G
      weight: 1
    - 
      problem: P17438
      caption: P9
      icon: basic/bird
      weight: 1

students:   #A list of exam students
    - email: student1@asdf.com   #Email from a student enrolled in the exam course (required)
      invited: 1    #If contest = 1, this means that the student has been invited and must not be ranked
          
    - email: student2@asdf.com
 
    - email: student3@asdf.com

Exam Info

Address: .../exams/username:examname
Method: GET
Description: Gives information about the specified exam. Returns a YAML document which follows the same format as the one used to create an exam.


Student Passwords

Address: .../exams/username:examname/passwords
Method: GET
Description: Gives the exam password for each exam student. Returns a YAML document which follows this format:

---
name: demo_exam1   #The name of the exam
title: First Demo Exam1   #The title of the exam
course: demo   #The name of the course the exam belongs to
passwords:   #The list of all the exam students emails and their exam passwords. If the exam is open, all the passwords will be empty.
    student1@asdf.com: CLOUCREA
    student2@asdf.com: SLAHOUMI

Delete Exam

Address: .../exams/username:examname
Method: DELETE
Description: Deletes the specified exam.


Start Exam

Address: .../exams/username:exam_name/actions/start
Method: PUT
Description: Starts the exam.

Problems

Uploaded Problems

Address: .../problems
Method: GET
Description: Returns a list of the uploaded problems. The YAML document returned will follow this format:

---
P12345:
    - ca
    - en
P54321:
    -ca
P34512:
    -en

New Problem

Address: .../problems
Method: PUT
Description: Uploads a problem. To do so, the user must have an account in the Jutge machine (otherwise, contact the administrator in info@jutge.org) A YAML document with the following format must be sent:

---
path: "Jutge@jutge.org:problems/mydir/myproblem.pbm"   #The path of the problem directory, relative to the home folder of the user account
password: password   #The problem password (optional)
languages:   #The languages available for the problem
    - ca
    - en


Yet to be documented:

    # curl https://user:password@jutge.org/services/problems/P12345/update
    # curl -F 'file=@problem.tgz' -X POST https://user:password@jutge.org/services/problems/P12345/update-upload
    # curl -F 'url=yoururl' -X POST https://user:password@jutge.org/services/problems/P12345/update-url
    

Yet to be implemented:

    # curl -F 'file=@problem.tgz' -X POST https://user:password@jutge.org/services/problems/add-upload
    # curl -F 'url=yoururl' -X POST https://user:password@jutge.org/services/problems/add-url