QTIEngine REST API

From QTITools Wiki

Jump to: navigation, search

The original QTIEngine doesn’t provide any web service interface for remote application to retrieve. What we have done is adding RESTful Web services to use the functions provided by QTIEngine. These methods can be found at QTIEngine/grails-app/RestController.groovy

Contents

[edit] Status

This has been merged into QTIEngine trunk (revision 2447). The installation instructions below are for the original version.

[edit] Installation

Check out the latest version from svn://svn.forge.ecs.soton.ac.uk/projects/easihemobile/QTIEnginePei, you can directly deploy the service on your server using QTIEngine-0.1.war file. If it succeeded, you could find the service running at http://yourservername/QTIEngine

[edit] Main methods

  • newSession(), sample url http://yourservername/QTIEngine/rest/newSession, the output is a session id as String
  • upload(), used to upload QTI file. Input parameters are required such as jsession and actionUrl that is sent through url QueryString, the output is a returned xml file
  • playItem(), used to play a single QTI item. Input params: jsessionid (required), actionUrl(required), the actionUrl will be a parameter in the post form
  • playTest(), used to play QTI content package. Input params: jsessionid (required), actionUrl (required) ,imageUrl (optional, if it’s necessary to specify image url).
  • report(), used to generate final report only for test not item. Input params: jsessionid (required, in query string), actionUrl(required, we insert it in the post form). There should be a parameter with key as “report”
  • Localize (private). Localize is not a public interface. It can only been used inside QTIEngine. This method is in RestService.groovy in QTIEngine/grails-app/services/. The detailed explanation of this method can be found on easihe technical document.

[edit] newSession

Example URL: http://qtiengine.qtitools.org/rest/newSession

HTTP Method: GET

POST body: none required.

Returns: a (32-byte?) hexadecimal string. This is a unique identifier for your session. You will need to pass it to the other REST requests. It is the whole body of the HTTP response.

[edit] upload

Example URL: http://qtiengine.qtitools.org/rest/upload;jsessionid=92117D905C409836CA5EBF6DDD927C84?actionUrl=http://www.example.com/handleAnswer

  • jsessionid is the session ID received from newSession. Is it actually needed? Maybe for playTest?
  • actionUrl is the URL to put in the action attribute of the form tag (e.g. <form action='http://www.example.com/handleAnswer'>). It is where the user's answers are sent, so the actionUrl page can forward them onto playItem for marking.

HTTP Method: POST

POST body: The Content-Type of the body must be multipart/form-data, as you must send the contents of an XML file containing a QTI item (or a ZIP file containing the files for a QTI assessment) in the part named uploadedContent. You may also pass the actionUrl in the POST body rather than in the query string.

Returns: After a redirect, the request returns an XML response which includes the XHTML to display to the user. The structure of the XML is:

  • <xml>
    • <root>
      • <status>
      • <page>

Note 1: You MUST set the User-Agent of the request, otherwise it returns a 500 Internal server error due to a NullPointerException. This is because it checks to see if the User-Agent .contains() various browser names!

Note 2: You MUST follow redirections, as the first response 302 redirects you to a URL that 'plays' the item.

[edit] playItem

Example URL: http://qtiengine.qtitools.org/rest/playItem/0;jsessionid=92117D905C409836CA5EBF6DDD927C84?actionUrl=http://www.example.com/handleAnswer

  • jsessionid is the session ID received from newSession. Is it actually needed? Maybe for playTest?
  • actionUrl is the URL to put in the action attribute of the form tag (e.g. <form action='http://www.example.com/handleAnswer'>). It is where the user's answers are sent, so the actionUrl page can forward them onto playItem for marking.
  • /0 is the 'id' according to Grails. It must be there, otherwise it all fails!

HTTP Method: GET (or POST)

POST body: The above claims the jsessionid should be in the POST body, but this is not necessary - it may be a matrix argument. You may pass the actionUrl in the POST body rather than in the query string, but what would be the point?

Returns: The request returns an XML response which includes the XHTML to display to the user, as in upload.

Note: No need to follow redirects or user agent.

[edit] Implementation

A sample usage of the QTIEngine Web Service is Discrete Maths Website, source code can be checkout from svn://svn.forge.ecs.soton.ac.uk/projects/easihemobile/DiscreteMathsDeploy.

[edit] Documentation

The detailed technical document and user guide can be found here

Retrieved from "http://wiki.qtitools.org/wiki/QTIEngine_REST_API"
Personal tools