LTI of Magic API

All of the information on LTI of Magic is programmatically available. You can call the API to get the current information out. You can also help add to the magic by registering your learning platform here. Then not only can your users see the apps and ratings, but they can also post app ratings back to LTI of Magic through your platform. Find out how at the bottom of the page

json | jsonp | atom

Introduction

APIs are cool. This one returns paginated JSON responses. There's no auth required for anything other than posting comments and reviews. All pagination information is included in the JSON response body.

App List

Returns a list of all known apps. Includes some summary information around the number of ratings and comments, as well as all information needed to configure and place the apps in a learning system.

GET /api/v1/apps 
{
  "meta": 
    {
      "next": "http://url.for/more/objects/if/any"
    },
  "objects": [
    {
      "id": "unique_identifier",
      "name": "Human Readable App Name",
      "extensions": ["multiple", "values"], // possible values: editor_button, resource_selection, user_nav, course_nav, account_nav
      "added": "2012-03-27T00:00:00Z",
      "avg_rating": 3.5,
      "banner_url": "http://example.com/240x125.png",
      "logo_url": "http://example.com/72x72.png",
      "launch_url": "http://example.com/app.launch",
      "any_key": true,
      "short_description": "Short app description",
      "comments_count": 21,
      "ratings_count": 45,
      "preview": {
        "url":"/twitter.html",
        "height":475
      },
      "categories": ["list of", "human-readable", "category names"],
      "levels": ["multiple", "values"], // possible values: "K-6th Grade", "7th-12th Grade", "Postsecondary"
      "description": "Longer app description",
      "config_url": "http://more.info/available/below"
    },
    { ... },
    { ... }
  ]
}

Optional parameters

level optional Filter to only apps that are marked for the specified grade level. The levels are available on the home page, and are all, K-6th Grade, 7th-12th Grade, and Postsecondary
category optional Filter to only apps that are categorized for the specified category. The categories are available on the home page, and are all, Community, Content, Math, Open Content, Science, Study Helps, Textbooks/eBooks, and Web 2.0
recent optional Filters to only apps have been added in the past 24 weeks. If less than 6 apps have been added in the last 24 weeks, it will go back farther until at least 6 apps are returned. Setting this value to anything other than an empty string will apply the filter.
platform optional Filters to only apps that can be used in the specified platform. This is a bit of a placeholder parameter, since right now there are only two options, Canvas and anything other than Canvas. As more apps and extensions are added, more platforms will be explicitly supported.
extension optional Filters to only apps that support the specified extension. Available extensions are all, editor_button, resource_selection, user_navigation, and course_navigation

Most of the information is consistent across all apps. preview is an optional value, and there are some possible configuration options listed below:

Possible Configuration Return Values

config_directions This app doesn't have a standardized way to configure it, so instead it will return some HTML code containing directions on how to manually configure the app.
config_url

If config_options is not provided, then this is the url that can be queried to retrieve the XML configuration for this app.

If config_options is provided, then it will contain a list of options that can be specified by the user to help specify app configuration. These options should be appended to config_url as query parameters. The format of the options is below. 

{
    "name": "query_parameter_key",
    "description": "Human-readable description", 
    "required": true,
    "type": "text", // possible values: text, checkbox
    "value": "default_query_parameter_value"
},
{ ... },
{ ... }

config_urls

This value provides a list of configuration URLs rather than a single configuration URL. config_options can still be specified as with config_url. The format of the URL list is below. 

{
  "url": "http://example.com/config.xml",
  "description": "Human-readable description"
},
{ ... },
{ ... }

App Details

Returns information on a single app. This doesn't provide any additional information than what's available in the app list response.

GET /api/v1/apps/:app_id 
{
  "id": "unique_identifier",
  "name": "Human Readable App Name",
  // Same as above
},

App Reviews List

Returns a paginated list of reviews for the specified app. Reviews may have come from multiple sources, including from the site itself using Twitter logins, or from other platforms/apps that have registered. More information on registering an app is available in the "contributing" section.

GET /api/v1/apps/:app_id/reviews 
{
  "objects": [
    {
      "user_avatar_url": "http://example.com/user/avatar/50x50.png",
      "source_name": "Human-readable name of platform/app where user posted",
      "tool_name": "Human-readable name of the app",
      "rating": 3, // out of 5
      "source_url": "http://example.com/platform_or_app/homepage",
      "user_name": "User name",
      "user_url": "http://example.com/user/profile",
      "id": 1,
      "comments": "user-provided comments, if any",
      "created": "Jun 19, 2012"
    }
  ],
  "meta": {
    "next": "http://example.com/more/reviews"
  }}

Contributing Reviews

Allows adding ratings and reviews from a registered platform or app. Required/optional fields are listed below. For more information on registering an app, please contact @whitmer.

POST /api/v1/apps/:app_id/reviews 
{
  "user_avatar_url": "http://example.com/user/avatar/50x50.png",
  "source_name": "Human-readable name of platform/app where user posted",
  // Same as above
}

Required/optional parameters

access_token required This is the access token provided by this site to the platform/app after registration. This should be kept secret (i.e. server-side only -- don't put it in your JavaScript), otherwise anyone can post comments and ratings as if they were your platform/app.
rating required This is an integer from 1 to 5.
user_name required This is the human-readable name for the commenting user within your platform/app.
user_id required This is the unique identifier for the user.
user_url optional This is the public profile URL for the user, if any.
user_avatar_url optional This is the URL to a public avatar image for the commenting user, if any.
comments optional This is the plaintext comments provided by the user.

Retrieving a Review

You can retrieve a specific review (to see for example if the current user has already reviewed the specified app) by calling. Requires the same user_id and access_token used when posting the review.

GET /api/v1/apps/:app_id/reviews/:access_token/:user_id 
{
  "user_avatar_url": "http://example.com/user/avatar/50x50.png",
  "source_name": "Human-readable name of platform/app where user posted",
  // Same as above
}