5. API Modules #

Note not all RESTFul functions are implemented.

If you encounter an restful API method that is not implemented, please let us know at support@aura-software.com.

5.1. List Of Parameters Available To All Methods #

For the API documentation that follows, for the sake of brevity we will omit in the description of each individual method the generic parameters that can be passed to each method.

These are described in more depth here:

• Response Format
• Access Modes
• Using Regular Expression Queries
• Specifying the List Of Fields To Be Returned

Parameters related to response format: #

Parameters related to access method: #

Note, you must specify ONE OF:

• api_key
• realm_guid AND realm_secret_key
• sc_app_id AND sc_secret_key [DEPRECATED]

Parameters that control the data to be returned. #

See specifying the list of fields to be returned for more information.

5.2. API Key #

The API Key interface allows for the creation of API keys for Bright Server.

5.2.1. Method: create #

Create a new API key.

5.2.1.1. HTTP Model: #

5.2.1.2. Parameters #

5.2.1.3. Return Data #

Returns a JSON document of the new record. HTTP Code is set to 201 (item created).

5.2.1.4. Example: #

curl -w "%{http_code}" -d 'sc_app_id=RQIBAXU49I
&sc_secret_key=nCwrTDSy1MzaeyhN0TFfi3uH3huzlu6CNmyHUG5N
&user_email=admin@aura-software.com' https://[BRIGHT URL]/bright/api/v2/api_key/

{
 "access_token":"a440b1ad868bc76716d22b4b827db77e",
 "created_at":"2012-12-18T12:16:29Z",
 "expires_at":null,
 "id":139,
 "course_provider_id":6,
 "token_type":null,
 "updated_at":"2012-12-18T12:16:29Z",
 "user_id":12
}
201

Note that this is a POST request, so you must configure your client appropriately. In the case of curl, this is accomplished with the -d flag.

The ‘-w %{http_code}’ piece allows you to view the returned HTTP code.

5.2.1.5. HTTP Codes #

5.3. Course #

5.3.1. Determining your :id for create and update #

For courses, Bright maintains a GUID that can be used as the :id field when using create, update, gcreate, or gupdate methods.

If course provider is SCORMCloud, this will be identical to the SCORMCloud course id.

For other course providers, the GUID will be a Bright generated unique ID.

5.3.2. Method: Index #

The index method allows the api user to fetch a course list.

When using the course#index method with an Api key, where the API key is for a particular learner, it is often desireable to return the learner’s registration data on each course selected. This lets the API client avoid having to query the learner’s data for each course returned. You can do this with the include_registrations parameter.

5.3.2.1. HTTP Model: #

5.3.2.2. Parameters #

All Bright API calls respond the parameters specified in List of Parameters Available To All Methods.

Parameters unique to this method, not included in above:

Control Parameters #

Control parameters are not filters and cannot be used with Using Regular Expression Queries.

Filter Parameters #

Filter parameters restrict the rows to be returned. Any filter parameter can be used with a regular expression, see Using Regular Expression Queries.

5.3.2.3. Example #

curl -w "%{http_code}" 'https://[BRIGHT URL]/bright/api/v2/course.json?course_guid=16-4fbd9ea698bce

5.3.2.4. HTTP Codes #

5.4. Invitation #

5.4.1. Method: add_learners #

5.4.1.1. HTTP Model #

5.4.1.2. parameters #

api_template

learners

name

nodelay

skip_external_initialization

unlearners

5.4.1.3. HTTP Codes #

5.4.1.4. Example #

curl -w "%{http_code}" 'https://[bright-url]/bright/api/v2/invitation/add_learners.json?nodelay=1&api_template=extended&name=xxx&learners=%5B%22admin%40aura-software.com%22%5D&realm_guid=sJtL8PtZG8S0z9bxkjPQ&realm_secret_key=PcQVlfCTIUebps3T268XKzAXvdzFpgc5svkM0uu38Zw'

5.4.1.5. Return Data #

If api_template request parameter isn’t set to extended, the API will respond with the invitation document:

{
  "id": 103,
  "license": true,
  "avoid_duplicate_registrations": false,
  "custom": "{\"license\":true,\"order_id\":10592,\"course_guids\":[\"0215JCHCMscorm12.3cdd5a65-0ec2-44a-c5a1f-37d9283757ce\"],\"license_data\":{\"2051JCHMCscorm1.23cdd56a-5e0c2-44ac-a51f-739d283757ce\":{\"seats_available\":5}},\"initiating_site\":\"localhost\",\"initiating_user\":\"support@aura-software.com\"}",
  "description": null,
  "enabled": true,
  "learners": [
    "support@aura-software.com"
  ],
  "name": "this73807a",
  "no_updates_allowed": false,
  "course_guids": [
    "2c3dd5a65-0ec2-44ac-a51f-37d9283757ce"
  ],
  "registration_guids": [
    "895-XWv_74NgkYTl03_zXIqXwg",
    "895-DY11XFd4ooLiJeGcx7HE3w"
  ],
  "realm_id": 1
}

When api_template is set to extended, the response looks like:

{
  "record": {
    "id": 103,
    "created_at": "2015-11-25T16:40:27.914Z",
    "updated_at": "2015-11-25T16:40:27.914Z",
    "realm_id": 10,
    "name": "this73807a",
    "description": null,
    "enabled": true,
    "custom": "{\"license\":true,\"order_id\":10592,\"course_guids\":[\"2c3dd5a65-0ec2-44ac-a51f-37d9283757ce\"],\"license_data\":{\"2c3dd5a65-0ec2-44ac-a51f-37d9283757ce\":{\"seats_available\":5}},\"initiating_site\":\"localhost\",\"initiating_user\":\"support@aura-software.com\"}",
    "avoid_duplicate_registrations": false,
    "no_updates_allowed": false,
    "invitation_template_id": null,
    "license": true,
    "course_guids": [
      "2c3dd5a65-0ec2-44ac-a51f-37d9283757ce"
    ],
    "learners": [
      "support@aura-software.com"
    ]
  },
  "registration_guids": {
    "support@aura-software.com": {
      "2c3dd5a65-0ec2-44ac-a51f-37d9283757ce": {
        "title": "My Course",
        "registration_guid": "895-XWv_74NgkYTl03_zXIqXwg"
      }
    }
  },
  "messages": [
    "Success!  Found and reused existing registration (895-XWv_74NgkYTl03_zXIqXwg) for support@aura-software.com on 'My Course' as part of license 'this73807a'."
  ]
}

5.5. Realm User #

For learners, its generally not necessary to prepopulate realm users as creating a registration implicitly creates the user.

It is possible to create them via the API and also manipulate their custom field as well.

5.5.1. Method: index #

5.5.1.1. HTTP Model #

5.5.1.2. parameters #

email

5.5.1.3. HTTP Codes #

5.5.1.4. Example #

5.5.1.5. Return Data #

5.5.2. Method: create #

Creates a new realm user. You must use a realm guid and secret key (or api key creating bound to a realm key) to create a realm user.

5.5.2.1. Parameters #

5.5.2.2. HTTP Codes #

5.5.2.3. Example #

curl -w "%{http_code}" 
'https://[BRIGHT URL]/bright/api/v2/realm_user/gcreate.xml?
api_key=2a84a6ddb229c13bc945874b69fab8ba&
email=bretx@aura-software.com&
custom=foo'
<?xml version="1.0" encoding="UTF-8"?>
<realm-user>
  <created-at type="datetime">2013-07-03T05:26:21Z</created-at>
  <custom>foo</custom>
  <id type="integer">1743</id>
  <realm-id type="integer">4</realm-id>
  <realm-role-id type="integer">1</realm-role-id>
  <updated-at type="datetime">2013-07-03T05:26:21Z</updated-at>
  <user-id type="integer">1686</user-id>
</realm-user>
201

5.5.3. Method: update (gupdate) #

Update a realm user. You must use a realm guid and secret key (or api key creating bound to a realm key) to update a realm user.

5.5.3.1. Parameters #

5.5.3.2. HTTP Codes #

5.5.3.3. Example #

curl -w "%{http_code}" 
'https://[BRIGHT URL]/bright/api/v2/realm_user/gupdate.xml?
api_key=2a84a6ddb229c13bc945874b69fab8ba&
email=bretx@aura-software.com&
custom=foox'
200

5.6. Registration #

5.6.1. Determining your :id for create and update #

For registrations, Bright maintains a GUID that can be used as the :id field when using create, update, gcreate, or gupdate methods.

If course provider is SCORMCloud, this will be identical to the SCORMCloud registration id.

For other course providers, the GUID will be a Bright generated unique ID.

5.6.2. Format of return data #

5.6.3. Method: index #

The index method allows the api user to query registrations.

5.6.3.1. HTTP Model #

5.6.3.2. parameters #

last_only

course_guid

learner_id

refresh_if_launched

crawl

5.6.3.3. HTTP Codes #

5.6.3.4. Example #

curl -w "%{http_code}" 'https://[BRIGHT URL]/bright/api/v2/registration.json?
api_key=2a84a6ddb229c13bc945874b69fab8ba&
learner_id=bret@aura-software.com&
course_guid=16-4fbd9ea698bce

5.6.3.5. Return Data #

5.6.4. Method: create #

Creates a new registration. Can be used in a single call that can be used to return an existing registration if one exists, or create a new one if it does not.

5.6.4.1. Parameters #

5.6.4.2. HTTP Codes #

In case of errors accessing the SCORMCloud API, a message including the error is returned (error code 403):

{
"error_code":"4",
"error_message":"The maximum number of registrations has been reached.",
"error_url":"https://cloud.scorm.com/api?email=..."
}

Please note if you are using JSONP, since there are limited facillities to capture errors via JSONP, we will return error code 200, with the error block above. Otherwise you might find it difficult to correctly handle this error.

5.6.4.3. Example #

For a successful request returned will be an XML or JSON document of the SCORMCloud registration. Note this example is using the gcreate alias (using an HTTP get).

curl -w "%{http_code}" 
'https://[BRIGHT URL]/bright/api/v2/registration/gcreate.json?
api_key=2a84a6ddb229c13bc945874b69fab8ba&
learner_id=bret@aura-software.com&
course_guid=16-4fbd9ea698bce&
sc_app_id=XXXYYYYZZZ&
sc_secret_key=nCwrTDSy1MzaeyhN0TFfi3uH3huzlu6CNmyHUG5N&
dont_duplicate=t'
{
 "attempts"=>2,
 "complete"=>"complete",
 "course_result"=>'<?xml version="1.0" encoding=...?> <rsp>...</rsp>',
 "crawl_error_msg"=>nil,
 "crawl_status"=>"success",
 "crawl_type"=>"course",
 "created_at"=>"2012-12-21T08:39:12Z",
 "full_result"=>nil,
 "id"=>5336,
 "last_crawled_at"=>"2012-12-12T16:33:33Z",
 "learner_id"=>"bret@aura-software.com",
 "number_of_crawl_errors"=>0,
 "provider_completed_at"=>nil,
 "course_guid"=>"20-NSFoundationPostTrainingQuiz",
 "provider_created_at"=>"2012-12-12T16:32:04Z",
 "deleted"=>nil,
 "provider_errcode"=>nil,
 "provider_error_message"=>nil,
 "provider_accessed_at"=>nil,
 "registration_guid"=>"79c0dd35-139-048258-16e-9a1561b0a85d",
 "score"=>99.2,
 "course_provider_id"=>10,
 "course_id"=>509,
 "success"=>"succeeded",
 "totaltime"=>100.0,
 "updated_at"=>"2012-12-21T08:39:12Z"
}

5.6.5. Method: launch_url #

The launch_url method is used to a get a unique, transient URL for course launch in direct response to a course launch event. Note, these cannot be cached, as they will expire.

5.6.5.1. HTTP Model #

5.6.5.2. parameters #

launching

review

redirect_url

tags

5.6.5.3. HTTP Codes #

5.6.5.4. Example #

5.6.5.5. Return Data #

5.7. StoredQuery #

5.7.1. Method: initialize #

Initialize is generally not necessary, but can be used in fresh installs of Bright Server to initialize the stored queries with a query_scope of ‘bright’.

5.7.1.1. HTTP Model #

5.7.1.2. parameters #

5.7.1.3. HTTP Codes #

5.7.1.4. Example #

5.7.1.5. Return Data #

5.7.2. Method: run #

5.7.2.1. HTTP Model #

5.7.2.2. parameters #

name

query_scope

format

5.7.2.3. HTTP Codes #

5.7.2.4. Example #

5.7.2.5. Return Data #

5.8. Template #

5.8.1. Method: index #

5.8.1.1. HTTP Model #

5.8.1.2. parameters #

name

markup

mimetype

5.8.1.3. HTTP Codes #

5.8.1.4. Example #

5.8.1.5. Return Data #

5.8.2. Method: create #

5.8.2.1. Parameters #

5.8.2.2. HTTP Codes #

5.8.2.3. Example #

5.8.3. Method: update (gupdate) #

5.8.3.1. Parameters #

5.8.3.2. HTTP Codes #

5.8.3.3. Example #