IMS Public Draft
IMS Public Draft

# A REST API for Tool Settings in multiple formats

Public Draft - Content-Item Message
Date Issued: 7 April 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 © 2014 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.

Join the discussion and post comments on the LTI Public Forum: http://www.imsglobal.org/community/forum/categories.cfm?catid=44

© 2014 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.
v1.0 Public Draft - Revision: 7 April 2014

## Abstract

This specification defines a REST API for reading and updating Tool Settings.

## Table of Contents

## 1. Introduction

This specification defines a REST API for reading and updating Tool Settings. Following common conventions, the API uses a different HTTP verb for each type of operation: GET for read and PUT for update.

In the IMS LTI standard, Tool Settings may be attached to certain resources within the Tool Consumer system. In particular, settings may be attached to `LtiLink`, `ToolProxyBinding`, and `ToolProxy` resources. Each of these resource types is a kind of `ToolSettingsContainer`. Through the REST API described in this document, a client may request settings from one particular container. By including the `bubble` query parameter, the client may request that the response contain settings from "higher-level" containers as well. For example, a client may request settings from an `LtiLink` resource and with `bubble=all`, the client will also receive settings from the learning context that contains the link plus settings defined at the system level (within the ToolProxy).

## 2. Representations

Tool Settings accessed through this REST API are represented by JSON documents in the following formats:
application/vnd.ims.lti.v2.toolsettings+json
application/vnd.ims.lti.v2.toolsettings.simple+json

When requesting settings via an HTTP GET request, the client specifies the desired format with the `Accept` header. When submitting settings via an HTTP PUT request, the client declares the format of the supplied JSON document with the `Content-Type` header.

## 3. URL Templates

Implementations of this REST API must offer an endpoint for accessing Tool Settings from each of three different types of containers: `LtiLink`, `ToolProxyBinding`, and `ToolProxy`. This specification does not mandate any particular URL templates for these endpoints, but the following templates are recommended:

    {+base}/lti/links/{link_id}/custom
    {+base}/lis/{context_type}/{context_id}/bindings/{vendor_code}/{product_code}/custom
    {+base}/lti/ToolProxy/{tool_proxy_guid}/custom

where `base` is the base URL, and the path parameters are defined as follows:

link_id
  The local identifier for an LtiLink.
context_type
  The simple name for the context type, e.g. Group, CourseSection, CourseTemplate, etc.
context_id
  The local identifier for the context
vendor_code
  The vendor code for a ToolProxy that is bound to the learning context
product_code
  The product code for a ToolProxy that is bound to the learning context
tool_proxy_guid
  The globally unique identifier for a ToolProxy

For example, these templates might yield something like the following URL values:

    https://lms.example.com/lti/links/402854/custom
    https://lms.example.com/lis/CourseSection/9283/bindings/acme.com/assessment-tool/custom
    https://lms.example.com/lti/ToolProxy/e6b6f6cc253a4d23ad57defbbd2a8e37/custom

The first URL provides access to tool settings scoped to a particular LtiLink. The second URL provides access to tool settings scoped to a particular learning context. The third URL provides access to system wide tool settings.

A Tool Consumer that implements this REST API must declare its URL templates within the Tool Consumer Profile. The templates are for information purposes and there is no contract that the Tool Consumer must support all possible endpoints that can be derived from each template. The The recommended practice is to have the Tool arrange for the Tool Consumer to send fully formed endpoints in the launch requests by specifying certain variables as launch parameters. The LTI standard defines the following variables:

LtiLink.custom.url
  The endpoint URL for accessing link-level tool settings
ToolProxyBinding.custom.url
  The endpoint URL for accessing context-level tool settings
ToolProxy.custom.url
  The endpoint URL for accessing system-wide tool settings

## 4. Service Methods

### 4.1 GET

To get a collection of Tool Settings, the client submits an HTTP GET request to the appropriate endpoint in accordance with the following rules:

- The request may contain the query parameters specified in Table 1.
- The request must contain the HTTP headers as specified in Table 2.

Parameter | Description
--- | ---
bubble | This query parameter specifies that the response should contain Tool Settings not only from the scope targeted by the endpoint URL, but also all higher-level scopes. For example, if the request is submitted to an LtiLink resource and the `bubble` parameter is present, then the response would include link-level, context-level and system-level settings. There are two possible values for the `bubble` parameter: `all` and `distinct`. When `bubble=all`, the server will return all tool settings from all the relevant scopes. This option cannot be used with the `application/vnd.ims.lti.v2.toolsettings.simple+json` media type. When `bubble=distinct`, the server will return tool settings from all the relevant scopes, but duplicates will be removed. That is to say, if a property with the same name appears in more than one scope, then the response will contain the property from the lowest-level scope only; the corresponding property from higher-level scopes will be omitted from the response.

Table 1. Query Parameters

Request Header Name | Value
--- | ---
Accept | A comma-separated list containing at least one of the following media types: `application/vnd.ims.lti.v2.toolsettings+json` `application/vnd.ims.lti.v2.toolsettings.simple+json`

Table 2. Required HTTP Headers for GET Request

Table 3 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 `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.
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.

Table 3. Possible responses from a GET method

### 4.2 PUT

To update a collection of Tool Settings, the client submits an HTTP PUT request to the appropriate endpoint in accordance with the following rules:

- The submitted JSON document must contain settings only for the particular collection referenced by the endpoint URL. If a client wishes to submit settings to more than one collection, it must make separate calls to each collection.
- The request must contain the HTTP Headers listed in Table 4.
- The request body must contain a JSON document in the format defined by the Content-Type request header.

Request Header Name | Value
--- | ---
Content-Type | One of: application/vnd.ims.lti.v2.toolsettings+json application/vnd.ims.lti.v2.toolsettings.simple+json
AUTHORIZATION | Authorization parameters dictated by the OAuth Body Hash Protocol

Table 4. Required HTTP Headers for PUT Request

Table 5 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.

Table 5. Possible responses from a PUT method

## About this Document

Title: | A REST API for Tool Settings in multiple formats
Editor: | Stephen Vickers (IMS Global)
Version: | 1.0
Version Date: | 7 April 2014
Release: | Public Draft
Status: | IMS Public Draft
Purpose: | This document is made available for review and comment by the public community at large.
Document Location: | Join the discussion and post comments on the LTI Public Forum: http://www.imsglobal.org/community/forum/categories.cfm?catid=44

### List of Contributors

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

Viktor Haag | Desire2Learn | Bracken Mosbacker | Instructure
Brad Humphrey | Instructure | Claude Vervoort | Cengage
Greg McFall | Pearson | Stephen Vickers | IMS Global Learning Consortium

IMS Global Learning Consortium, Inc. (“IMS Global”) is publishing the information contained in this (“Specification”) for purposes of scientific, experimental, and scholarly collaboration only.

IMS Global makes no warranty or representation regarding the accuracy or completeness of the Specification. This material is provided on an “As Is” and “As Available” basis.

The Specification is at all times subject to change and revision without notice.

It is your sole responsibility to evaluate the usefulness, accuracy, and completeness of the Specification as it relates to you.

IMS Global would appreciate receiving your comments and suggestions.

Please contact IMS Global through our website at http://www.imsglobal.org

Please refer to Document Name: IMS Global Learning Tools Interoperability - Content-Item Message Public Draft v1.0
Revision: 7 April 2014