3. Quick Start #

In the section we will quickly work throw the steps of connecting to the Bright API, authenticating, and generating API calls.

3.1. Using The Examples #

A quick way to get started is to look at

https://github.com/aura-software/bright-api-examples

It shows two methods of API access:

Access Key
Ream Guid/Secret Key

And the most common form of API use cases.

3.2. Prerequisite Data #

Your Bright API URL. This will be provided to you and is based on where your Bright server is installed, and what DNS entry is used to access it. Don’t know it? Ask us at support@aura-software.com!

You should also have your Bright Realm ID and Secret key, which can be obtained from Bright Support.

See the section on access modes for your alternatives for authenticating with Bright Server.

For the purposes of this example, we will use the following:

Bright API URL: https://[BRIGHT URL]/bright/api/v2
Bright Realm Guid: sJtL8PtZG8S0z9bxkjPQ&
Bright Realm Secret Key: PcQVlfCTIUebps3T268XKzAXvdzFpgc5svkM0uu38Zw

For your environment, use your realm guid and secret key provided by Bright Support.

With the above information, we can already use our API. To do so, we can test this straight from curl a command line tool that is easy to install on most systems.

When learning the Bright API, we recommend you start by assembling some simple curl commands from your command line in order to get a feel for what is possible.

So let’s get our list of courses from our API:

curl 'https://[BRIGHT URL]/bright/api/v2/course.xml?realm_guid=sJtL8PtZG8S0z9bxkjPQ&
realm_secret_key=PcQVlfCTIUebps3T268XKzAXvdzFpgc5svkM0uu38Zw'

If you’ve executed this correctly, you’ll get a result like:

And the result:


  <?xml version="1.0" encoding="UTF-8"?>
  <scorm-cloud-courses type="array">
    <scorm-cloud-course>
      <course-provider-id type="integer">6</course-provider-id>
      <created-at type="datetime">2012-11-26T12:10:40Z</created-at>
      <custom></custom>
      <id type="integer">184</id>
      <metadata>{"title":"ENT Foundation - Post Training QUIZ",
	             "description":"",
				 "duration":"0",
				 "typicaltime":"0",
				 "keywords":null}
 	  </metadata>
      <registration-count type="integer">1</registration-count>
      <sc-course-id>1-507727747154e</sc-course-id>
      <size type="integer">157758</size>
      <title>System Test Course</title>
      <updated-at type="datetime">2013-01-17T16:20:10Z</updated-at>
      <versions type="integer">-1</versions>
    </scorm-cloud-course>
  </scorm-cloud-courses>

3.3. Specifying a results format #

The Bright API lets you specify the format of your results, but appending a suffix to the require URL prior to the query string.

3.3.1. Overview #

Regardless of API call you are making, you must always specify an interface format when interacting with the Bright API.

This must be specified

Append to the URL prior to query parameters, like:

[BRIGHT_URL].(format=xml|json|csv]?query_parameters=….

While in previous software versions, in some cases the request format was inferred, and ‘.json’ could be ommitted, this model is deprecated and the request format is now required.

3.3.2. Fetching an XML result #

To fetch your results in XML format, append a ‘.xml’ to the url, before the request parameters. For example

https://[BRIGHT URL]/bright/api/v2/course.xml

3.3.3. Fetching an JSON result #

Let’s say if you are using the API from Javascript, and you’d like your results back as JSON. Easy, just rewrite the URL to use ‘course.json’ instead of ‘course.xml’

curl 'https://[BRIGHT URL]/bright/api/v2/course.json?
sc_app_id=RQIBAXU49I&
sc_secret_key=nCwrTDSy1MzaeyhN0TFfi3uH3huzlu6CNmyHUG5N'

And the result (formatted for readibility:

[
 {
	 "created_at":"2012-11-26T12:10:44Z",
	 "id":187,
	 "registrations":2,
	 "course_guid":"1-5098f07394cbd",
	 "course_provider_id":6,
	 "size":1599415,
	 "title":"Proktologie",
	 "updated_at":"2012-11-27T22:30:40Z",
	 "versions":-1
 },
 {
	 "created_at":"2012-11-29T16:11:53Z",
	 "id":200,
	 "registrations":1,
	 "course_guid":"1-50b63e903dd43",
	 "course_provider_id":6,
	 "size":2211931,
	 "title":"Proktologie",
	 "updated_at":"2012-12-07T15:48:43Z",
	 "versions":-1
 }
]

3.3.4. Fetching a CSV result #

To fetch your results in CSV format, append a ‘.csv’ to the url, before the request parameters. For example

https://[BRIGHT URL]/bright/api/v2/course.csv

3.4. Using Regular Expression Queries #

Using regular expression query is simple with the Bright API.

For controllers that support it,

Registration
Course

You can specify query paramets like

curl 'https://[BRIGHT URL]/bright/api/v2/course.json?[key-logic]&
title_re=[a title regular expression]&
title_re=[a second regular expression]&
custom_re=[a matching expression on the custom field]
...

3.4.1. Complex Example #

In this example, we have a “pts available” field in the course custom field.

The query below selects out courses that have a number of points available >= 4.

wget -qO- 'https://[BRIGHT URL]/bright/api/v2/course.json?[key logic]&
custom_re=points_available\":\"([4-9]|[1-9]([0-9])+)'

3.4.2. Using Multiple Expressions On The Same Field. #

It is possible to repeatedly query the same field from multiple regular expressions. To do this, use a numerical suffix on the query parameter. So instead of custom_re, for example, use

custom_re0
custom_re1

etc.

wget -qO- 'https://[BRIGHT URL]/bright/api/v2/course.json?[key logic]&
custom_re0=points_available\":\"([4-9]|[1-9]([0-9])+)&custom_re1="category":"onboarding"'

Note:

This search is full text, including in custom [JSON] text.
Therefore you must support JSON syntax include ‘:’ assisgments.

3.5. Specifying the List Of Fields To Be Returned #

You can specify a set of fields to be returned by a Bright API call. This is an alternative method to use the “template=” approach.

To use the fields specification, just include the

 fields=field1,field2,...

query paramters.

For example, on the course controller, when using ‘include_registrations’, the following is valid:

fields=course_guid,title,custom,registrations.complete,registrations.registration_guid