IMS Public Draft

A REST API for LISResult Resources
in the application/vnd.ims.lis.v2p1.result+json Format

Public Draft
Date Issued: 15 December 2014
Latest version: http://www.imsglobal.org/lti

IPR and Distribution Notices

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the specification set forth in this document, and to provide supporting documentation.

IMS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on IMS's procedures with respect to rights in IMS specifications can be found at the IMS Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf.

Copyright © 2016 IMS Global Learning Consortium. All Rights Reserved.

Use of this specification to develop products or services is governed by the license with IMS found on the IMS website: http://www.imsglobal.org/license.html.

Permission is granted to all parties to use excerpts from this document as needed in producing requests for proposals.

The limited permissions granted above are perpetual and will not be revoked by IMS or its successors or assigns.

THIS SPECIFICATION IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NONINFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY USE OF THIS SPECIFICATION SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE CONSORTIUM, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER, DIRECTLY OR INDIRECTLY, ARISING FROM THE USE OF THIS SPECIFICATION.

 

 

© 2016 IMS Global Learning Consortium, Inc.
All Rights Reserved.
The IMS Logo and Learning Tools Interoperability (LTI) are trademarks of the IMS Global
Learning Consortium, Inc. in the United States and/or other countries.

Abstract

This specification defines a REST API for creating, reading, updating and deleting LISResult resources.

Table of Contents

1. Introduction

This specification defines a REST API for creating, reading, updating and deleting LISResult resources. Following common conventions, the API uses a different HTTP verb for each type of operation: POST for create, GET for read, PUT for update and DELETE for delete

Implementations of this REST API may be incomplete; a given server might support only a subset of the HTTP verbs. A server that supports the complete API will expose two different kinds of endpoints: a container endpoint for receiving POST requests and item endpoints for manipulating individual instances. This specification document does not prescribe a method for discovering the endpoint URLs.

2. LISResult Representations

LISResult resources manipulated via this REST API are represented as JSON documents in the application/vnd.ims.lis.v2p1.result+json format. For detailed information about this media type, see [LISResult-media-type].

It is also possible to obtain a paginated list of LISResult resources from a ResultContainer in the application/vnd.ims.lis.v2.resultcontainer+json format. For detailed information about this media type, see [ResultContainer-media-type].

3. URL Templates

Implementations of this REST API must offer an endpoint for managing the contents of the ResultContainer associated with each LineItem. This specification does not mandate any particular URL template for such endpoints, but the following template is recommended: 
{+context}/lineitems/{itemId}/results

where itemId is an identifier for a LineItem and context is the URL for the learning context with which that LineItem is associated.

For example, the URL for a ResultContainer might look something like this: 

https://lms.example.com/course/289376/lineitems/721508/results

Technically, clients never GET the ResultContainer itself. Instead, they GET a paginated list of Result resources available from the container, where each Page has its own URL. This specification does not mandate any particular URL template for Pages, but it is recommended that implementations follow the conventions suggested by the W3C Linked Data Platform specification. According to these conventions, the first page would have a URL of the form 

{+context}/lineitems/{itemId}/results?firstPage
and subsequent pages would have URLs of the form 
{+context}/lineitems/{itemId}/results?p={pageNumber}
where pageNumber is the sequential number of the page or some key that uniquely identifies the page. For instance, these templates might yield the following URL values: 
https://lms.example.com/course/289376/lineitems/721508/results?firstPage 
https://lms.example.com/course/289376/lineitems/721508/results?p=2 
https://lms.example.com/course/289376/lineitems/721508/results?p=3 
https://lms.example.com/course/289376/lineitems/721508/results?p=4

Each individual Result must have its own URL. This specification does not mandate any particular URL template for individual Result resources, but the following template is recommended: 

{+context}/lineitems/{itemId}/results/{resultId}
where resultId is an identifier for the Result. The identifier must be unique within the parent LineItem.

The server (either ToolConsumer or Tool) must declare in the service_offered section of its profile RestServices for Result and ResultContainer resources. The server MUST NOT declare a RestService for the various Pages of the container.

4. Service Methods

4.1 POST

To create a new LISResult instance within the server, a client submits an HTTP POST request to the server's LISResult container endpoint in accordance with the following rules:

 

Request Header NameValue
AuthorizationAuthorization parameters dictated by the OAuth Body Hash Protocol
Table 1.  Required HTTP Headers for POST Request

 

Table 2 describes the possible responses from the POST method.

HTTP Status Description
201 Created

The response has succeeded.

The entity body of the response contains a full description of the newly created Result in the application/vnd.ims.lis.v2p1.result+json format. The Result has the same properties supplied in the request, but it also contains the @id property.
400 Bad Request The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.
401 Unauthorized The client did not authenticate properly.
403 Forbidden The request was valid but the server is refusing to allow it at this time.
500 Internal Service Error The server encountered an unexpected condition which prevented it from fulfilling the request.
Table 2.  Possible responses from a POST method

4.2 GET

To get a representation of a particular LISResult instance, the client submits an HTTP GET request to the resource's REST endpoint, in accordance with the following rules:

 

Request Header NameValue
AuthorizationAuthorization parameters dictated by the OAuth Body Hash Protocol
Acceptapplication/vnd.ims.lis.v2p1.result+json
Table 3.  Required HTTP Headers for GET Request

 

Table 4 describes the possible responses from the GET method.

HTTP Status Description
200 OK The request was successful.

The response contains a JSON document in the format defined by the application/vnd.ims.lis.v2p1.result+json media type.
301 Moved Permanently The URI for the requested resource has changed.

In this case, the response body is empty, and the new URI is provided in the Location header. The client should GET the resource from the new location, and furthermore, it should send all future requests to the new location as well.
307 Temporary Redirect The requested resource resides temporarily under a different URI.

In this case, the response body is empty, and the temporary URI is defined by the Location header field. The client should GET the resource at the temporary URI, but future requests should continue to be sent to the original URI.
401 Unauthorized The client did not authenticate properly.
404 Not Found The server has not found anything matching the request URI.
500 Internal Service Error The server encountered an unexpected condition which prevented it from fulfilling the request.
Table 4.  Possible responses from a GET method

4.3 GET from a ResultContainer

To get a paginated list of LISResult resources from a ResultContainer, the client submits an HTTP GET request to the container endpoint in accordance with the following rules:

 

ParameterDescription
limitSpecifies the maximum number of items that should be delivered per page. This parameter is merely a hint. The server is not obligated to honor this limit and may at its own discretion choose a different value for the number of items per page.
Table 5.  Query Parameters

 

Request Header NameValue
AuthorizationAuthorization parameters dictated by the OAuth Body Hash Protocol
Table 6.  Required HTTP Headers for GET Request

 

Table 7 describes the possible responses from the GET method.

HTTP Status Description
200 OK

The request was successful.

The response body contains the first Page of LISResult resources in the format defined by the application/vnd.ims.lis.v2.resultcontainer+json media type. This Page has its own URL which is distinct from the URL of the ResultContainer. The URL of the first Page is supplied in the Content-Location header.

Clients should be aware that a server may send a 303 redirect to the first Page (see below) instead of delivering this Page directly in the entity body. Likewise a server may send a 301 or 307 redirect.
301 Moved Permanently The URI for the requested resource has changed.

In this case, the response body is empty, and the new URI is provided in the Location header. The client should GET the resource from the new location, and furthermore, it should send all future requests to the new location as well.
303 See Other This status code signals that the ResultContainer itself cannot be delivered in the response. Instead, the client may receive the first page from a paginated list of LISResult resources at the address specified by the Location header.
307 Temporary Redirect The requested resource resides temporarily under a different URI.

In this case, the response body is empty, and the temporary URI is defined by the Location header field. The client should GET the resource at the temporary URI, but future requests should continue to be sent to the original URI.
401 Unauthorized The client did not authenticate properly.
404 Not Found The server has not found anything matching the request URI.
500 Internal Service Error The server encountered an unexpected condition which prevented it from fulfilling the request.
Table 7.  Possible responses from a GET method

4.4 PUT

To update a particular LISResult instance, the client submits an HTTP PUT request to the resource's REST endpoint in accordance with the following rules:

 

Request Header NameValue
Content-Typeapplication/vnd.ims.lis.v2p1.result+json
AuthorizationAuthorization parameters dictated by the OAuth Body Hash Protocol
Table 8.  Required HTTP Headers for PUT Request

 

Table 9 describes the possible responses from the PUT method. In all cases, the response body is empty.

HTTP Status Description
200 OK The request was successful.
401 Unauthorized The client did not authenticate properly.
403 Forbidden The request was valid but the server is refusing to allow it at this time.
404 Not Found The server has not found anything matching the request URI.
500 Internal Service Error The server encountered an unexpected condition which prevented it from fulfilling the request.
Table 9.  Possible responses from a PUT method

4.5 DELETE

To delete a particular LISResult instance, the client submits an HTTP DELETE request to the resource's REST endpoint in accordance with the following rules:

 

Request Header NameValue
AuthorizationAuthorization parameters dictated by the OAuth Body Hash Protocol
Table 10.  Required HTTP Headers for DELETE Request

 

Table 11 describes the possible responses from the DELETE method. In all cases, the response body is empty.

HTTP Status Description
200 OK The request was successful and the resource has been deleted.
401 Unauthorized The client did not authenticate properly.
403 Forbidden The request was valid but the server is refusing to allow it at this time.
404 Not Found The server has not found anything matching the request URI.
500 Internal Service Error The server encountered an unexpected condition which prevented it from fulfilling the request.
Table 11.  Possible responses from a DELETE method

5. References

[LISResult-media-type]
Stephen Vickers. LISResult JSON Binding in the application/vnd.ims.lis.v2p1.result+json format. IMS Public Draft. 1 April 2015.
[ResultContainer-media-type]
Stephen Vickers. ResultContainer JSON Binding in the application/vnd.ims.lis.v2.resultcontainer+json format. IMS Public Draft. 1 April 2015.

About this Document

Title: A REST API for LISResult Resources in the application/vnd.ims.lis.v2p1.result+json Format
Editor:Stephen Vickers (IMS Global)
Version: 2.0
Version Date: 15 December 2014
Release: Public Draft
Status: IMS Public Draft
Purpose: This document is made available for review and comment by the public community at large.

List of Contributors

The following list of individuals contributed to the authoring of this document:

Viktor HaagDesire2LearnCharles SeveranceUniversity of Michigan
Brad HumphreyInstructureJohn TibbettsVitalsource
Greg McFallPearsonClaude VervoortCengage
Bracken MosbackerInstructureStephen VickersIMS Global Learning Consortium
Padraig O'hiceadhaHoughton Mifflin Harcourt