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.
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
|
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
|
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.
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
|
Address: .../courses/username:coursename
Method: DELETE
Description: Deletes the specified course.
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
|
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
|
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.
Address: .../lists/username:listname
Method: DELETE
Description: Deletes the specified list.
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.
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 |
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.
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).
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.
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.
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.
Address: .../competitions/username:competition_name/actions/next
Method: PUT
Description: Starts the next round in the competition.
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!
Address: .../competitions/username:competition_name/actions/finish
Method: PUT
Description: Finishes a competition. No more round can be played when a competition ends.
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
|
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
|
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.
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
|
Address: .../exams/username:examname
Method: DELETE
Description: Deletes the specified exam.
Address: .../exams/username:exam_name/actions/start
Method: PUT
Description: Starts the exam.
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
|
Address: .../problems
Method: PUT
Description: Uploads a problem. To do so, the user must have an account in the Jutge machine. 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
|
# 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
# 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