PrairieLearn API

Overview

There are five main PrairieLearn components:

• Database
• PrairieLearn API Server
• PrairieLearn Web Server
• PrairieLearn WebApp
• Questions

The PrairieLearn Web Server sends the PrairieLearn WebApp code and resources to the browser. The PrairieLearn Web Server only serves static resources and it does not computation itself.

The PrairieLearn API Server and PrairieLearn WebApp communicate over the Server API (see below).

The PrairieLearn API Server is the only component that communicates with the Database.

Each Question includes both a server and client JavaScript component. The PrairieLearn API Server executes communicates with the server.js Question component. The PrairieLearn API Server also transmits the client.js Question component to the PrairieLearn WebApp as JavaScript source-code. The WebApp then executes and communicates with the client.js component.

The communication between both the Server and the WebApp with the Question occurs over the Question API (see below).

Server API

The PrairieLearn server presents a RESTful HTTP API (Level 2 on the Richardson Maturity Model).

Server API: Identifiers

All ID objects are strings. They should be treated as opaque identifiers and should not be interpreted for any information.

Server API: Method calls

The general pattern is that a collection /collect can generally be accessed in three ways:

• A GET to /collect returns all the objects in the collection, each with a minimal representation containing at least the <id> property. An optional query string to the GET may allow for filtering of the return list by certain object properties.

• A POST to /collect creates a new object in the collection and returns its <id>. The POST data may need to contain some of the properties of the new object. The newly created object will typically have some of its properties filled in by the server upon creation.

• A GET to /collect/<id> returns the single specified object in complete form.

Server API: JSON object specifications

{
  "qid": <string>,
  "title": <string>
}

{
  "uid": <string>,
  "name": <string>
}

{
  "qiid": <string>
  "title": <string>
  "date": <date>,
  "uid": <string>,
  "tiid": <string>
  "qid": <string>,
  "vid": <string>,
  "params": <params>,
  "trueAnswer": <trueAnswer> // optional
  "options": <object> // optional
}

{
  "params": <params>,
  "trueAnswer": <trueAnswer>
}

{
  "sid": <string>
  "date": <date>,
  "uid": <string>,
  "qiid": <string>,
  "submittedAnswer": <submittedAnswer>,
  "overrideScore": <number>, // optional
  "practice": <boolean>, // optional
  "score": <number>,
  "feedback": <feedback>,
  "trueAnswer": <trueAnswer>
}

{
  "score": <number>,
  "feedback": <feedback>
}

{
  "tid": <string>,
  "title": <string>,
  "type": <string>,
  "number": <number>
}

{
  "tiid": <string>,
  "uid": <string>,
  "tid": <string>
}

{
  "name": <string>,
  "title": <string>
}

{
  "pid": <string>,
  "createDate": <date>,
  "createUID": <string>,
  "subject": <string>,
  "commitHash": <string>,
  "refNames": <string>,
  "authorName": <string>,
  "authorEmail": <string>,
  "authorDate": <string>,
  "committerName": <string>,
  "committerEmail": <string>,
  "committerDate": <string>
}

Server API: Error reporting

The PrairieLearn server only uses the following HTTP status codes:

Question API

The PrairieLearn Questions consist of server.js and client.js components. These present a JavaScript API for communication with the PrairieLearn Server and the PrairieLearn WebApp. The Question components server.js and client.js should be loaded with RequireJS to obtain the corresponding <server> and <client> objects.

Question server API

Question client API

Sample execution flows

Solving a question with a random variant

The steps to ask and answer a question with a random variant are:

1. Decide which <qid> we want to attempt.

2. POST to /qInstances with a partial qInstance of the form:

   {
     "uid": <uid>,
     "qid": <qid>
   }
   

3. The return value will be a completed qInstance object of the form:

   {
     "qiid": <qiid>,
     "date": <date>,
     "uid": <uid>,
     "qid": <qid>,
     "params": <params>
   }
   

Take the randomly generated variant ID <vid> from here.

1. GET the question client code from /questions/<qid>/<vid>/client.js

2. Call client.initialize() and client.renderQuestion(), passing a callback for change notifications.

3. Wait until the change callback fires and client.isComplete() returns true, and then further wait until the user indicates the desire to submit the answer for grading.

4. Call client.getSubmittedAnswer() to obtain a <submittedAnswer> object.

5. POST to /submissions with a partial submission object of the form:

   {
     "uid": <uid>,
     "qiid": <qiid>,
     "submittedAnswer": <submittedAnswer>
   }
   

6. The return value will be a completed submission object of the form:

   {
     "sid": <sid>,
     "date": <date>,
     "uid": <uid>,
     "qiid": <qiid>,
     "submittedAnswer": <submittedAnswer>,
     "score": <number>,
     "feedback": <feedback>,
     "trueAnswer": <trueAnswer>
   }
   

7. Show the score to the user and call client.setTrueAnswer() and client.renderAnswer() to display the true answer.

SimpleClient

Rather than implementing a general client interface, the SimpleClient library allows the easy creation of questions with a certain structure.