RSE 0003

Runestone API

Assumptions:

• All of the GET API calls require a user to be authenticated
• All of the information returned by GET is for the authenticated user
• If the user is an instructor they will get information for all students in their course
• All of the POST API calls except for /click require a user to be authenticated
• All information return by GET is relative to the book the user is registered for

Current API endpoints

Endpoint	Description
hsblog	generic clickstream logging
runlog	log and save runs and errors
saveprog	saves a program
getprog	return a program
savegrade	save a grade
getuser	return user info
getnumonline	count of active users
getnumusers	count of all users
savehighlight	save information for new highlight
deletehighlight	remove
gethighlights	get all highlights for a user
updatelastPage	save last page viewed
getCompletionStatus	get completion status for this subchapter
getAllCompletionStatus	get completion status for all chapters/subchapters
getlastpage	get last page viewed
getCorrectStats	get statistics for an assessment
getStudentResults	get my results for an assessment
getAggregate results	get aggregate results for an assessment
getPollResults	return polling results
gettop10Answers	get top 10 most popular answers for a fill in the blank question
getSphinxBuildStatus	get current build status from the mule
getassignmentgrade	get grade for an assignment
getCodeDiffs	get list of diffs between version of code -- not used
getCoachingHints	get code coach hints

OPTION 1

HTTP method	URI	Description
GET	api/v1/log	return all log data for this user
GET	api/v1/code/[divid]	return all code or return latest version of code for divid
GET	api/v1/assess/mchoice	return all mulitple choice answers for this user or latest for divid
GET	api/v1/assess/fillblank	return all fillin the blank answers for this user or latest for divid
GET	api/v1/assess/shortanswer	return all short answers for this user or latest for divid
GET	api/v1/highlight/[pageid]	return all users highlights or all highlights for the given page
GET	api/v1/user	check if user logged in, and return user information including last page etc.

This option would be a "cleaning up" of our current API which has no particular naming convention or underlying structure.

OPTION 2

HTTP method	URI	Description
GET	/api/v1/chapters/[id]	return all chapter ids and metadata for this book or all data for a specified chapter
GET	/api/v1/subchapters/[id]	return all subchapter ids and metadata for this book or all data for a specified subchapter
GET	/api/v1/assessments/[id]	return all assessments for this user or all data on a specific assessment
GET	/api/v1/code/[id]	return all activecode ids for this user or latest version for a specific id
GET	/api/v1/click/[id]	return all click log data for this user or all click information about a specific id
GET	/api/v1/users

This second option is much more focused around the page/subchapter. We ought to think about the terminology, its easy to be book focused but we don't want to exclude lectures and labs.

page : { pageid,
         courseShortName,
         chapterShortName,
         subChapterShortName,
         userid,
         lastUpdate,
         pageVisitTimes = [],
         assessments = [], 
         highlights = [],  
         activecodes = [] 
     }

assessment : { divid,
               type
               answer
               correct
     }
  

The idea is that we make one call on page load to get the dynamic data to plug into the page, as well as we will know if the user is logged in or not with this same call. As the user interacts with the page.

This is a document focused model that may very well lend itself to MongoDB rather than SQL.

There may be a big resource impact as we get everything with one request rather than many requests. Although the result will be larger than any one request it is not going to be so big as to cause performance problems.

When a page is PUT, the server will update any relevant new data. The page should be POSTED upon first visit and PUT thereafter.

The page will be stored on every change in localstore and then updated on departure?

The use of localstorage for this model opens up localstore for everyone, whether they are logged in users or not.