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/
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/
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.
LineItem resources.This specification defines a REST API for reading, creating, updating and deleting LineItem resources. Following common conventions, the API uses a different HTTP verb for each type of operation: GET for read, POST for create, 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.
LineItem resources accessed through this REST API are represented by documents in a variety of formats including:
LineItem resources have Cool URLs. This means that there is a single URL for each resource and the URL does not change for different representations (or versions) of the resource. Each representation is defined by a different media type, and clients access specific representations through content negotiation.
It is also possible to obtain a paginated list of LineItem resources from a LineItemContainer in the application/vnd.ims.lis.v2.lineitemcontainer+json format. For detailed information about this media type, see [LineItemContainer-media-type].
{+context}/lineitems
where context is the URL for the learning context.
For example, the URL for the LineItemContainer in a certain course might look something like this:
https://lms.example.com/course/289376/lineitems
Technically, clients never GET the LineItemContainer itself. Instead, they GET a paginated list of LineItem 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?firstPage
and subsequent pages would have URLs of the form
{+context}/lineitems?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?firstPage https://lms.example.com/course/289376/lineitems?p=2 https://lms.example.com/course/289376/lineitems?p=3 https://lms.example.com/course/289376/lineitems?p=4
Each individual LineItem must have its own URL. This specification
does not mandate any particular URL template for individual LineItem resources, but
the following template is recommended:
{+context}/lineitems/{itemId}
where itemId is an identifier for the LineItem that is unique within
the associated learning context.
The server (either ToolConsumer or Tool) must declare in the service_offered
section of its profile RestServices for LineItemContainer and LineItem
resources. The server MUST NOT declare a RestService for Page resources.
| Request Header Name | Value |
|---|---|
| Content-Type | application/vnd.ims.lis.v2.lineitem+json |
| Authorization | Authorization parameters dictated by the OAuth Body Hash Protocol |
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 LineItem in the |
| 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. |
| 500 Internal Service Error | The server encountered an unexpected condition which prevented it from fulfilling the request. |
| Request Header Name | Value |
|---|---|
| Authorization | Authorization parameters dictated by the OAuth Body Hash Protocol |
| Accept | A comma-separated list containing at least one of the following media types: |
Table 4 describes the possible responses from the GET method.
| HTTP Status | Description |
|---|---|
| 200 OK | The request was successful.
The response contains a document in one of the formats specified by the Accept header. |
| 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 |
| 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 |
| 401 Unauthorized | The client did not authenticate properly. |
| 404 Not Found | The server has not found anything matching the request URI. |
| 406 Not Acceptable | The requested resource is only capable of generating content not acceptable according to the Accept headers sent in the request. |
| 500 Internal Service Error | The server encountered an unexpected condition which prevented it from fulfilling the request. |
| Parameter | Description |
|---|---|
| limit | Specifies 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. |
| activityid | The id for an Activity. The result set will be filtered so that it includes only those LineItems that are associated with this Activity. If omitted, the result set will include all LineItems that the client has permission to see. |
| Request Header Name | Value |
|---|---|
| Authorization | Authorization parameters dictated by the OAuth Body Hash Protocol |
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 LineItem resources in the format defined by the 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 |
| 303 See Other | This status code signals that the LineItemContainer itself cannot be delivered in the response.
Instead, the client may receive the first page from a paginated list of LineItem 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 |
| 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. |
| Request Header Name | Value |
|---|---|
| Content-Type | One of:
|
| Authorization | Authorization parameters dictated by the OAuth Body Hash Protocol |
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. |
| 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. |
| Request Header Name | Value |
|---|---|
| Authorization | Authorization parameters dictated by the OAuth Body Hash Protocol |
| Content-Type | The format for one specific representation of the LineItem resource that is to be deleted. If the Content-Type header is not specified, then all representations of the resource will be deleted. |
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. |
| 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. |
application/vnd.ims.lis.v2.lineitemcontainer+json format. IMS Public Draft. 15 December 2014.| Title: | A REST API for LineItem Resources in multiple formats |
|---|---|
| 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. |
The following list of individuals contributed to the authoring of this document:
| Viktor Haag | Desire2Learn | Charles Severance | University of Michigan |
| Brad Humphrey | Instructure | John Tibbetts | Vitalsource |
| Greg McFall | Pearson | Claude Vervoort | Cengage |
| Bracken Mosbacker | Instructure | Stephen Vickers | IMS Global Learning ConsortiumZ2 |
| Padraig O'hiceadha | Houghton Mifflin Harcourt |