Skip to Main Content

OpenSesame API 文件

Consuming the API:

The API features are broken up into 3 categories:

  1. The Catalog API allows you to pull course categories, tags, search results, and course metadata for display in your system.
  2. The LMS Integration API allows us to link user accounts between both systems to allow us to show the user which LMS systems their account is linked to. After a purchase they can choose which LMS system they want to deploy their courses to.
  3. The Course Metadata API allows you to pull metadata (and SCORM packages) of purchased courses for provisioning in your system.

In addition to the API implemention, you also will need to set up a page that we can hit for actions that are initiated by us (See 4 and 5 below). We chose the page approach (as opposed to back-end communication only) for a few reasons:

  • Security: having the user log into your site to complete the linking operations keeps us from ever knowing their credential and also ensures that we are linking the right user.
  • This allows maximum flexibility in terms of provisioning after purchase: You can have the user log into your full site to complete provisioning, have the page show in a lightbox on our site for a more integrated experience, or just tell them that the transfer is complete and they can log in to your site to complete setup.
  • Eventually we will offer your system as an option for any users who do not yet have an LMS. When they complete checkout they can choose your system as their LMS of choice and we can send them to your site along with the linking token thereby allowing you to set up their account and then pull the courses.

The use case for the end user that we are supporting initially looks like this:

  1. LMS system pulls catalog information for display to users. Users can drill into categories and select courses for purchase. It’s up to you how much or how little of the course metadata you show to the user or whether you cache the catalog on your side or pass through the requests as the user drills into the categories.
  2. When they choose a course you open a new window to our site with a url specified by us through the API. This link includes some information about the user like email, name, etc so that we can prefill that when they create an account. Navigating to this link brings up the course details page on our site with instructions welcoming them to OpenSesame.
  3. User can then continue to browse the catalog on our site.
  4. If the user completes their purchase, the confirmation page will offer them the option of linking their account to your system and provisioning the courses in their account. The linking mechanism is a request from our site to a page on yours including a token. You authenticate the user and then pass us back the token with a unique user identifier that we store and supply on subsequent provisioning requests.
  5. When a user who is already linked to your system completes an order we will present them with a link to provision their purchase on your system; that link will include your user identifier as supplied during the initial linking.  If the LMS chooses to implement the single sign portion of the api and if the user agrees then the lms can provide the service of logging the user into OpenSesame whenever they drill into the details of a course.

LMS Partner Setup:

Initial setup for LMS partners will be done by OpenSesame. An account Id and api key will be provided by OpenSesame and used in all api communication with OpenSesame.

OpenSesame API:

All Of the OpenSesame APIs are simple https calls which take HTTP form parameters and return JSON objects (http://www.json.org/) which detail all of the information about the specific request. For all operations the requests are sent to the same url (https://www.OpenSesame.com/API/).
 
All Request objects have these elements:
 AccountId:(String: The LMS AccountId),
 DateTime:(String dateTime of the request construction in mm/dd/yyyy hh:mm:ss format  in GMT)
 Operation:(String: One of the operations listed below),
 Version:(Number: The version of the API you have programed to interface with, for now pass 1)
 Operation specific parameters specified for the operation,
 Hash:(String: See Hash algorithm)
 
All Response objects have these elements:
JSON {
 RequestId:(Number: unique Id OpenSesame has assigned to your request),
 Success:(‘true’ or ‘false’ indicating the success or failure of your request),
 Error:(String: details as to the failure reasons or blank on success),
 DateTime:(String dateTime of the response construction in mm/dd/yyyy hh:mm:ss format in GMT)
 Operation specific parameters specified for the operation,
 Hash:(String: See Hash algorithm)
}
 
Hash algorithm: take the entire object after all desired values have been filled, remove the Hash parameter, and all leading and trailing whitespace, sorts all keys alphabetically attach the key to values using the ‘=’ character and the key value pairs together with ‘&’ characters. Remove all tab carraige return and newline characters. Prepend ‘/api?’ and hash the resulting string using sha1 and the LMS API Key. If you find that the hashes do not match on the Response side the response should be treated as suspect and discarded. Note: The Hashing algorithm is provided as part of the reference implementation.
 
Operations:
 
CourseCategoryList: This operation returns the valid string categories that are available to be  used when listing courses.

  •  Operation specific request parameters: none
  •  Operation specific response parameters:
    •  CategoryList:[category1,category2,...] where category1, category2, etc are strings.

 
CourseList: This operation returns the courses which match the specified tags, categories, and search term in pages of 10 results each

  • Operation specific request parameters:

    • CategoryList:[category1,category2,...] comma separated, where category1, category2, etc. are strings which are returned from the CourseCategoryList operation.
    • TagList:[tag1,tag2,...] comma separated,where tag1, tag2, etc are strings which are returned from the CourseTagList operation.
    • Search: The desired search string
    • Page: 0-indexed page number requested
  •  Operation specific response parameters:
    •  CourseList:[course1,course2,...] where course1, course2, etc are Course objects as defined below
    • TotalPages: number of pages or course results

 
Course (object)
{
 Title:(String: the title of the course),
 CourseGuid:(String: unique identifier for a course),
 Version:(Number: number defining the version of the course, the higher the number the newer the version.  This number will not be sequential and is for internal use only.),
 Description:(String: description of the course),
 PerSeatPrice:(Number: price per seat in USD),
 VolumeDiscountAvailable:(“true” or “false” if true then there is a site license available for this course and OpenSesame for this user),
 SiteLicenseAvailable:(“true” or “false” if true then there is a site license available for this course and OpenSesame for this user),
 SeatTime:(Number: the estimated number of minutes this course takes to complete)
 DetailUrl:(String: a url which can be followed to view the full course details and purchase the course if desired.
}
 
CoursePurchaseList: This operation returns the course purchases for a user which have been  shared with the requesting LMS.

  •  Operation specific request parameters:

    •  UserIdentifier:(String: identifier provided for the user when linking with your LMS)
  •  Operation specific response parameters:
    •  CoursePurchaseList:[coursePurchase1,coursePurchase2,... Where coursePurchase1, coursePurchase2, etc are CoursePurchase   objects as defined below

 
CoursePurchase (object)
{
 LicenseGuid:(String: the License provided by this purchase),
 Title:(String: the title of the course),
 CourseGuid:(String: unique identifier for a course),
 Version:(Number: number defining the version of the course, the higher the number the newer the version.  This number will not be sequential and is for internal use only.),
 Description:(String: description of the course),
 NumberOfSeats:(Number: The number of seats purchased with this license, -1 if a site license was purchased)
 SeatsRemaining:(Number: The number of seats remaining with this license, -1 if a site license was purchased)
}
 
GetSesameSeed: This Operation returns the Zip Scorm Package to play for a given license.

  • Operation specific request parameters:

    • LicenseGuid:(String: the License for the course t be launched.),
    • UserIdentifier:(String: identifier provided for the user when linking with your LMS)
  • Operation specific response parameters:
    • File:(String: the base64 encoded file contents which can be streamed or stored as the LMS desired for the SesameSeed)

 
LinkUser: This operation should be called after successful authentication to LMS on the LMS supplied hosted operation page as defined in the next section. This operation provides OpenSesame with an identifier that will be presented to LMS in further synchronization requests.

  • Operation specific request parameters:

    • Token:(String: token that was passed to the LMS signin frame on the url with the tagname “token”)
    • UserIdentifier:(String: the user identifier which is used to identify the user in future correspondence between OpenSesame and the LMS)
  • Operation specific response parameters: none

 

GetSignonToken: This operation should be called when a user who is already linked and who has agreed to allow your lms sso permission is browsing courses from opensesame in the lms(see LMS Hosted Operations below).  The token should be used in the construction of ech of the course detail urls with the tag name "sso" or dia one of the helper methods provided in the api wrapper you are using.

  • Operation specific request parameters:

    • UserIdentifier:(String: the user identifier which is used to identify the user in future correspondence between OpenSesame and the LMS)
  • Operation specific response parameters:
    • SignonToken:(String: token to be used for signing the user onto OpenSesame, see operation description for details.

 
LMS Hosted Operations: LMS must supply a url which will be used by OpenSesame to allow the user to authenticate with the LMS and signal the LMS to perform a synchronization operation. This url will receive the following url parameters:

  • Token:(string: identifier which is used to call VerifyUser after successful signin. Not required for “sync” operation)
  • UserIdentifier:(string: identifier previously provided by LMS to OpenSesame)
  • Action:(“link” or “sync” or “new”)
    • link: this is the first linking between the LMS and OpenSesame for this user. User came to OpenSesame from the LMS by clicking a course link.

      • LMS should respond to link command by calling LinkUser
    • sync: User is already linked between OpenSesame and the LMS.
      • LMS should respond to sync command by pulling course data from OpenSesame and prompting user to configure their newly-purchased courses
    • new: User is not currently linked and did not come to OpenSesame from the LMS.
      • LMS should respond to new command by creating a new account of the user, calling LinkUser, and then pulling course data from OpenSesame and prompting user to configure courses.
  • SsoGranted:("true" or "false) This parameter will only be sent of the lms has told OpenSesame to enable single sign on  for their LMS.  If true then the specified user has granted the LMS rights to sign them onto OpenSesame.  If false then the user has not granted rights and any attempt by the Lms to call the GetSignonToken operation for this user will result in a not authorized exception.  This parameter should be watched on every action because the user can choose to change this value at any time.

 
Impementation Resources:
OpenSesame provides phone and email support to LMS API partners as well as reference implementations in C#, PHP, and Java. Please contact us for API credentials and reference implementations.
 
 

 

 

Live Help