A REST API for Tool Settings in multiple formats

Abstract

Table of Contents

• 1. Introduction
• 2. Representations
• 3. URL Templates
• 4. Service Methods
• 4.1 GET
• 4.2 PUT
• About this Document

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

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

{+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

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

4.2 PUT

• 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.

About this Document

List of Contributors

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