REST API
========

This page describes the various REST API methods that may be called, what 
inputs/outputs they will accept/provide.

For almost all the API methods you will need to supply a ``username`` and 
``api_key`` (either as ``post`` or ``get`` parameters) otherwise you will get an
``HTTP 401 Unauthorized`` response

It is quite unlikely you will need to access these methods directly yourself, 
since the OppiaMobile client app handles all the API calls already.

By default all the methods will return JSON object(s).

Awards
------
Gets all the badges which have been awarded to the given user.

* Available methods: GET

* Required parameters:

	* ``username``
	* ``api_key``
	
* Example GET request::

 	http://localhost/api/v1/awards/?format=json&username=XXXX&api_key=XXXXXXXX
 

	
Badges
------
Gets all the badges that are currently available on the server.

* Available methods: GET

* Required parameters:

	* ``username``
	* ``api_key``
	
* Example GET request:: 

	http://localhost/api/v1/badges/?format=json&username=XXXX&api_key=XXXXXXXX

Course
------
Gets all the courses currently available on the server, and includes the link to
 download the course zip file

* Available methods: GET

* Required parameters:

	* ``username``
	* ``api_key``
	
* Example GET request:: 

	http://localhost/api/v1/course/?format=json&username=XXXX&api_key=XXXXXXXX
	
	
* Example GET request for downloading course zip file (also needs the required 
  parameters username and api_key)::

	http://localhost/api/v1/course/1/download/?username=XXXX&api_key=XXXXXXXX

Points
------
Gets all the points for the given user

* Available methods: GET

* Required parameters:

	* ``username``
	* ``api_key``
	
* Example GET request:: 

	http://localhost/api/v1/points/?format=json&username=XXXX&api_key=XXXXXXXX
	

Question
--------
For creating or returning a quiz question

* Available methods: GET, POST
* Required parameters (for both GET and POST requests):

	* ``username``
	* ``api_key``

* POST parameters:

	* ``title``  - required
	* ``type`` - required
	* ``responses`` - required, though may contain an empty set
	* ``props`` - optional set of properies
	
* Example GET request::

	http://localhost/api/v1/question/59/?format=json&username=XXXX&api_key=XXXXXXXX

* Example CURL POST request::

	curl --dump-header - -H "Accept: application/json" -H "Content-Type: 
		application/json" -X POST --data '{"title":"A woman has sexual 
		intercourse with a man who is HIV-positive. She is tested for HIV 
		infection two weeks after this sexual intercourse. Her HIV test is 
		negative. Should you trust this result?","type":"multichoice",
		"responses":[],"props":[{"name":"maxscore","value":"1.0000000"}]}' 
		"http://localhost/api/v1/question/?username=XXXX&api_key=XXXXXXXX"

Quiz
----
For creating or returning a quiz 

* Available methods: GET, POST
* Required parameters (for both GET and POST requests):

	* ``username``
	* ``api_key``

* POST parameters:

	* ``title``  - required
	* ``description`` - required
	* ``questions`` - required, though may contain an empty set
	* ``props`` - required, though may contain an empty set

* Example GET request::

	http://localhost/api/v1/quiz/59/?format=json&username=XXXX&api_key=XXXXXXXX

* Example CURL POST request::

	curl --dump-header - -H "Accept: application/json" -H "Content-Type: 
		application/json" -X POST --data '{"title":"ANC 4 SAQs","description":
		"Hormonal Regulation of the Female Reproductive System","questions":[],
		"props":[]}' "http://localhost/api/v1/quiz/?username=XXXX&api_key=XXXXXXXX"

QuizAttempt
-----------

For posting a quiz attempt 

* Available methods: POST
* Parameters (all required):

	* ``username``
	* ``api_key``
	* ``quiz_id`` 
	* ``maxscore``
	* ``score``
	* ``attempt_date``
	* ``responses`` - a set of responses (for each question)

* Example CURL POST request::

	curl --dump-header - -H "Accept: application/json" -H "Content-Type: 
		application/json" -X POST --data '{"quiz_id":"27","maxscore":30,"score": 
		10,"attempt_date":"2012-12-18T15:35:12","responses":[{"question_id":"409", 
		"score":0,"text":"Orlando"},{"question_id":"410","score":0,"text": 
		"Jacksonville beaches"},{"question_id":"411","score":10,"text":"Dade  
		County"}]}'  
		"http://localhost/python/api/v1/quizattempt/?username=XXXX&api_key=XXXXXXXX"
 

QuizProps
---------

For creating or returning quiz properties. Usually used to add a ``digest`` 
property for the quiz. 

* Available methods: GET, POST
* Required parameters (for both GET and POST requests):

	* ``username``
	* ``api_key``

* POST parameters:

	* ``name``  - required
	* ``value`` - required
	* ``quiz`` - required - URI reference to the quiz

* Example GET request::

	http://localhost/api/v1/quizprops/10aa48109651ee7f45af789c382131a4/?format=json&username=XXXX&api_key=XXXXXXXX

* Example CURL POST request::

	curl --dump-header - -H "Accept: application/json" -H "Content-Type: 
		application/json" -X  POST --data '{"name":"digest","value":
		"10aa48109651ee7f45af789c382131a4", "quiz":"/api/v1/quiz/636/"}' 
		"http://localhost/api/v1/quizprops/?username=XXXX&api_key=XXXXXXXX"
	

QuizQuestion
------------

For adding a question to a quiz

* Available methods: GET, POST
* Required parameters (for both GET and POST requests):

	* ``username``
	* ``api_key``

* POST parameters:

	* ``quiz`` - required - resource_uri to the quiz (will have been returned 
	  when the quiz was created)
	* ``question`` - required - resource_uri to the question (will have been 
	  returned when the question was created)
	* ``order`` - required 

* Example GET request::

	http://localhost/api/v1/quizquestion/1621/?format=json&username=XXXX&api_key=XXXXXXXX

* Example CURL POST request::

	curl --dump-header - -H "Accept: application/json" -H "Content-Type: 
		application/json" -X  POST --data '{"question":
		"/api/v1/question/1824/", "quiz":"/api/v1/quiz/356/", 
		"order":"5"}'
		 "http://localhost/api/v1/quizquestion/?username=XXXX&api_key=XXXXXXXX"
		
Register
--------

For user registration (obviously no api_key required)

* Available methods: POST

* Parameters (all required):

	* ``username``
	* ``password``
	* ``passwordagain``
	* ``email``
	* ``firstname``
	* ``lastname``

* Example CURL POST request::

	curl --dump-header - -H "Accept: application/json" -H "Content-Type: 
		application/json" -X POST --data '{"username":"demo","password":
		"mypassword", "email":"demo@myemail.com","passwordagain":"mypassword",
		"firstname":"demo","lastname":"user"}' 
		http://localhost/api/v1/register/

* POST request will return a JSON object in the following format::

	{
		"api_key": "9fa50a5e49cce4d0a5ab89c6c21faec284630e7b", 
		"badges": 0,
		"email": "demo@myemail.com", 
		"first_name": "demo", 
		"last_name": "user", 
		"points": 100, 
		"username": "demo"
	}
		 
Response
--------
For adding a possible response to a quiz question

* Available methods: GET, POST
* Required parameters (for both GET and POST requests):

	* ``username``
	* ``api_key``

* POST parameters:

	* ``question`` - required - resource_uri to the question (will have been 
	  returned when the question was created)
	* ``order`` - required 
	* ``title`` - required 
	* ``score`` - required 
	* ``props`` - optional

* Example GET request::

	http://localhost/api/v1/response/4050/?format=json&username=XXXX&api_key=XXXXXXXX

* Example CURL POST request::

	curl --dump-header - -H "Accept: application/json" -H "Content-Type: 
		application/json" -X  POST --data 
		'{"question":"/python/api/v1/question/1829/","title":"my response", 
		"order":5, "score":10, "props":[{"name":"feedback","value":"Correct, 
		well done!"}]}' 
		"http://localhost/api/v1/response/?username=XXXX&api_key=XXXXXXXX"

Schedule
--------
For getting the activity schedule for a course (for the given user)

* Available methods: GET
* Required parameters:

	* ``username``
	* ``api_key``

* Example GET request::

	http://localhost/api/v1/schedule/45/?format=json&username=XXXX&api_key=XXXXXXXX
		
Tag
---
For getting the tags and number of courses for each tag

* Available methods: GET
* Required parameters:

	* ``username``
	* ``api_key``

* Example GET request (for getting the set of tags)::

	http://localhost/api/v1/tag/?format=json&username=XXXX&api_key=XXXXXXXX
 
* Example GET request (for getting the courses tagged with tag_id 2)::

	http://localhost/api/v1/tag/2/?format=json&username=XXXX&api_key=XXXXXXXX
	
Tracker
-------

For submitting a track of an activity

* Available methods: POST
* Parameters:

	* ``username`` - required
	* ``api_key`` - required
	* ``digest`` - required 
	* ``data`` - optional - a JSON object of additional data to store along with
	  this tracker object
	* ``completed`` - optional - 0 or 1 (defaults to 0)

* Example CURL POST request::

	curl --dump-header - -H "Accept: application/json" -H "Content-Type: 
		application/json" -X POST --data '{"digest":
		"ddeee1c1eec4f842b8b704dbd5889dcc","data":"{}","completed":1}' 
		"http://localhost/api/v1/tracker/?username=XXXX&api_key=XXXXXXXX"

* POST request will return a JSON object in the following format::

	{
		"badges": 8, 
		"completed": false, 
		"data": "", 
		"digest": "ddeee1c1eec4f842b8b704dbd5889dcc", 
		"points": 656, 
		"resource_uri": "/python/modules/api/v1/tracker/3912/", 
		"tracker_date": "2013-06-28T18:44:08.845329", 
		"user": "/python/api/v1/user/1/"
	}
			
User
----

For logging a user in

* Available methods: POST
* Parameters:

	* ``username`` - required
	* ``password`` - required

* Example CURL POST request::

	curl --dump-header - -H "Accept: application/json" -H "Content-Type: 
		application/json" -X POST --data '{"username":"myusername","password":
		"mypassword"}' "http://localhost/api/v1/user/"

* POST request will return a JSON object in the following format::

	{
		"api_key": "9fa50a5e49cce4d0a5ab89c6c21faec284630e7b", 
		"badges": 0, 
		"first_name": "demo", 
		"last_login": "2013-06-28T18:50:35.523539", 
		"last_name": "user", 
		"points": 100, 
		"resource_uri": "/python/api/v1/user/317/", 
		"username": "demo"
	}
