3.2.1 Retrieving a Token

To retrieve a token, you’ll be making a POST to the OAuth 2.0 token endpoint. To successfully get back a token, you will need the following pieces of information:

• Username - You will need a valid username for which to retrieve a token. This will be given to you by the endpoint administrator
• Client id - The client id is a unique id that identifies you, the caller, to the authentication system. This id is given to you by the endpoint administrator.
• Client secret - The client secret is a secret string that is known to both you, the caller, and the authorization endpoint. Again, this will be given to you by the endpoint administrator. Do not share your client secret with anyone else.

Once you’ve gathered those three pieces of information, you’ll need to prepare the client id and secret for inclusion on the request. The client id and secret are not included in plain-text on the POST. Instead, the client id and secret need to be appended together, Base64-encoded, and then included as a header value.

First, combine your client id and secret, separated by a colon (:)

Next, use a Base64 encoder to create an encoded version of that string. Your language of choice will have a Base64 encoder available or you can find one using a quick Google search. For this demo, I’ve used https://www.base64encode.org/. Running that string though a Base64 encoder, I get:

Now it’s time to make the request to the token endpoint to acquire a token. For the request, you’ll need to include two headers, and some JSON in the request body.

Example call:

POST https://imsglobal.org/ims/rs/v1p0/token

Example authorization header:

• Header key: Authorization
• Header value: Basic BASE64_ENCODED_STRING_GOES_HERE

Replace BASE64_ENCODED_STRING_GOES_HERE with the Base64 encoded version of your client and secret. For the example above, the value for the Authorization header would be “Basic bXlfaWQ6bXlfc2VjcmV0”

• Header key: Content-Type
• Header value: application/json

You need to tell the token endpoint that you’ll be passing JSON in the POST body

Example body:

In the body of the request, you need to tell the token endpoint what grant_type you’ll be using and which user id you’re attempting to retrieve a token for. In this case, you are using ‘client_credentials’ for the grant type. This is the grant type that uses client ids and secrets. For the username, replace user@schoolco.com with the username given to you by the authorization endpoint administrator.

Now that you’ve constructed your headers and included the grant type and username in the POST body, POSTing to the token endpoint will get you a token for accessing the resource search endpoints.

Example access token response from token endpoint:

        {
            "access_token": "3fb1738c61bb13ef4cfb5943cc18255c7cea41b9d7d3be59297f2fdd5a0f6b15",
            "expires_in": 2592000
        }
      

  3.4.1 For consumers:

If you are building queries that search by subject, you will want to limit your searches to subjects returned by the subjects endpoint. Searches for subjects not included in that list will likely result in no results. If you are not running subject-based searches then there is no reason for you to call this API.

  3.4.2 For providers:

This is your indicator to consumers which subjects they can search that will yield actual results. There is no requirement on your end for this data to be 100% timely so you can choose a method of returning this data that best fits your needs. Some options:

• Return a hard-coded list of supported subjects (simple)
• Query the list from for your repository and then cache it for a period of time (a little more costly)
• Query the list every time (most accurate, but the highest cost).

  3.4.3 Fetching Subjects

To retrieve the subjects supported by a particular resource repository, you will make a GET call to the /subjects endpoint. If the endpoint has been secured using OAuth 2.0, you’ll need to include the retrieved auth token as a header parameter in the request.

Example call:

GET https://imsglobal.org/ims/rs/v1p0/subjects

Example authorization header (if necessary):

• Header key: Authorization
• Header value: Bearer AUTH_TOKEN_GOES_HERE

Replace AUTH_TOKEN_GOES_HERE with the actual auth token received from the OAuth 2.0 token endpoint.

Example result:

        {
          "subjects": [
            {
              "identifier": 1,
              "name": "Mathematics",
              "parent": "0"
            },
            {
              "identifier": 2,
              "name": "Geometry",
              "parent": "1"
            },
            {
              "identifier": 4,
              "name": "Algebra",
              "parent": "1"
            }
          ]
        }
      

The result that comes back is a JSON array of subject objects. Each subject contains an identifier that uniquely identifies the subject in the resource repository, the name of the subject, and the identifier of this subject’s parent. Subjects can be hierarchical so it is up to you to (if desired) turn the flat subject array into the correct hierarchy based on the parent identifier relationships. In the result above, there is one top-level subject (Mathematics) and two child subjects (Geometry and Algebra) whose parent is Mathematics.

  3.5.1 A Simple Search

To fetch resources from a resource repository, make a GET against the /resources endpoint. If the endpoint has been secured using OAuth 2.0, you’ll need to include the retrieved auth token as a header parameter in the request.

Example call:

GET https://imsglobal.org/ims/rs/v1p0/resources

Example authorization header (if necessary):

• Header key: Authorization
• Header value: Bearer AUTH_TOKEN_GOES_HERE

Replace AUTH_TOKEN_GOES_HERE with the actual auth token received from the OAuth 2.0 token endpoint.

The resulting JSON returned from the /resources endpoint will be an array of Resource objects that match the filters passed in as query parameters. Because no parameters were passed in, the default behavior of the /resources endpoint it to return the first 100 results. A sample result-set looks like this:

          "resources": [
            {
              "id": 1,
              "name": "RESOURCE_001",
              "description": "This is a searchable resource - 001",
              "publisher": "Education Co.",
              "subject": [
                    "Mathematics"
              ],
              "url": "https://www.educationco.com/resources/1",
              … more attributes are here...
            },
            {
              "id": 2,
              "name": "RESOURCE_002",
              "description": "Another searchable resource - 002",
              "publisher": "Education Co.",
              "subject": [
                    "Geometry"
              ],
              "url": "https://www.educationco.com/resources/2",
              … more attributes are here...
            }
          ]
        }
      

In this case, the resource search returned two results. For this example, I’ve removed most of the attributes to save space. For a complete list of what can be returned for a resource, see the Resource Payload section of the LTI Resource Search REST/JSON bindings: https://www.imsglobal.org/sites/default/files/spec/lti-rs/v1p0/rest_binding/rsservicev1p0_restbindv1p0.html#TabUMLJSONMap_CoreClass_Resource

  3.5.2 Filtering Resources

To concentrate the list of resources returned by the /resources endpoint to something more specific, you’ll use the filter query parameter. Filters allow you to specify a data field, a predicate, and a value in order to refine the result-set returned by the /resources endpoint to a specific set of resources that match your criteria.

As an example, lets search for resources that are in one of the subjects listed above. To find all the resources with a subject of ‘Geometry’:

• Data field - This is the field containing the resource’s subject value. In our case, the data field would be ‘subject’.
• Predicate - We want resources that exactly match the subject name that we’re searching for so we use an equal sign ‘=’. The equals predicate does an exact match on the data field value.
• Value - The value to match on. In this case, we want resources with a subject value of ‘geometry’. All comparisons are case-insensitive so we can pass ‘geometry’ or ‘Geometry’ or ‘GeOmEtRy’ and get the same results. Because this is a string value, it needs to be enclosed in single quotes.

Putting them together, our filter becomes:

To add this as a filter in the query string, the filter will need to be URL encoded. The URL encoding process makes strings safe for being included as query parameters on a URL string. URL encoding the above filter turns it into:

For more information on URL encoding, see the following page: https://www.w3schools.com/tags/ref_urlencode.asp

To search the resource repository using the URL encoded filter, add it as the value for the filter query parameter at the end of the /resources endpoint.

Example call:

GET https://imsglobal.org/ims/rs/v1p0/resources?filter=subject%3D%27geometry%27

Example authorization header (if necessary):

• Header key: Authorization
• Header value: Bearer AUTH_TOKEN_GOES_HERE

Replace AUTH_TOKEN_GOES_HERE with the actual auth token received from the OAuth 2.0 token endpoint.

The above call will search the resource repository and return only resources marked as being in the Geometry subject.

For more details on which data fields can be searched and which predicates are supported, see the Searching for Resources section of the LTI Resource Search REST/JSON bindings: https://www.imsglobal.org/sites/default/files/spec/lti-rs/v1p0/rest_binding/rsservicev1p0_restbindv1p0.html#Main3p1

  3.5.3 Complex Filtering

Searches within the resource repository do not have to be limited to a single filter. Two filters can be chained together in order to refine the list of returned resources even further. Building on the example above, let’s say that the user not only wants to view resources in the Geometry subject, but that user particularly cares about resources having to do with triangles. Like before, we need to construct a filter using a data field, predicate, and value.

For this case, let’s use the ‘description’ data field. This is the field containing a detailed description of the contents of the resource. Since we don’t know the exact description of the resources we want, we really just want to find resources with ‘triangle’ in the description. To do this, you’ll use the ‘~’ operator. The tilde ‘~’ operator matches on resources that contain the value string anywhere within the data field. To find all resources with ‘triangle’ somewhere in the description, the filter would be:

Now that we have two filters, they’ll need to be combined into a single filter string. Filter strings can be combined using AND or OR. Using AND will only return resources that match both conditions. Using OR will return resources that match either of the conditions. For this case, we’ll use AND.

Like before, this will need to be URL encoded:

Now that the combined filter has been constructed, make the call just like before.

Example call:

Example authorization header (if necessary):

• Header key: Authorization
• Header value: Bearer AUTH_TOKEN_GOES_HERE

Replace AUTH_TOKEN_GOES_HERE with the actual auth token received from the OAuth 2.0 token endpoint.

The above call will now search the resource repository and return only resources marked as being in the Geometry subject that contain ‘triangle’ in their description.

  3.5.4 Errors

At some point in your filter construction, it is likely that you will make a mistake and construct an invalid query. Using the above case as an example, let’s say you forgot to wrap your filter value in single quotes.

Which, when URL encoded would be:

In the case when the resource search endpoint cannot parse your query due to poor construction, an error payload will be returned instead of an array of resources. If your filter happens to result in zero matches, the return payload will look like this:

        {
          "resources": []
        }
        
        If an error occurred, the payload will look like this:
        {
          "CodeMajor": "failure",
          "Severity": "error",
          "CodeMinor": "invalid_data",
          "Description": "Wrong filter parameter"
        }
      

It is very important to be able to distinguish between an empty result set and an error payload. The error payload’s ‘Description’ field will do its best to explain to you what went wrong. It’s also possible that your auth token was incorrect, in the wrong place, or expired. In the case of your query being rejected due to lack of authorization, the return payload will look like this:

        {
          "error": "Unauthorized"
        }
      

If you receive an ‘Unauthorized’ error, make sure that you included the auth token and that you included it in the right place. The most common authorization error is forgetting that your auth token needs to be preceded by the text “Bearer “.

  3.5.5 Sorting, Paging, and Field Selection

If you find yourself dealing with very large result sets, you may find yourself in need of the sorting, paging, or field selection functionality provided by the /resources endpoint. In the case above, it’s possible that the resource repository has hundreds of resources in the Geometry subject with ‘triangle’ in the description.

Tip: The exact number of resources that meet the filter criteria can be found by looking at the X-Total-Count header value on the response from the /resources endpoint.

To better find the specific resources that you’re looking for, result sets can be sorted by any of the available data fields. To sort the returned resources, you will use the following query parameters:

• sort - The name of the data field on which to sort the data. The full list of sortable data fields is available here: https://www.imsglobal.org/sites/default/files/spec/lti-rs/v1p0/rest_binding/rsservicev1p0_restbindv1p0.html#Main3p1
• orderBy - This will be either ‘asc’ or ‘desc’ depending on if you want your results sorted from A-Z or from Z-a.

For the original subject search, to sort the results by name in ascending (A-Z) order, the query would look like this:

If the number of returned results is overly large, you can request a specific page of data using the limit and offset query parameters.

• limit - The number of total records to return. Specifying a limit of 10 will only return 10 resources.
• offset - The index of the resource result to start with. If you consider your result set as an array, offset controls which array index your results will begin at. If an offset of 55 is specified, the /resources endpoint will only return the resources at index 55 and above. Offset is 0-based meaning that there is an item at index 0, an item at index 1, etc. so specifying an offset of 4 will cause your result set not to contain resources at indexes 0, 1, 2, and 3.

By combining limits and offsets, you can view small subsets of your data, letting you (if building a user interface) give your user the option of paging through the data in small chunks.

To view the first 10 records in the above result set (indexes 0 through 9 of the result array), your query would look like this:

The next page of data (indexes 10 through 19) could be fetched by increasing the offset to the index of the first record in the next page.

Tip: As a helper, the /resources endpoint will automatically generate paging URLs for you and include them in the response header under the “Link” key.

Last, if you only care about very specific resource fields, you can control which data fields are returned for each resource using the fields query parameter:

• fields - A comma-separated list of the fields you want returned for each resource

If you want to limit the data coming back from the /resources endpoint to just the name and subject of each resource, your fields parameter would look like this:

Combining the above queries, you can get the names and subjects of page 4 (indexes 30-39) of the Geometry resources sorted by name: