2. General Usage #
The Bright API is used to interact with Bright Server. Typical things you might do with Bright are
- access data about learners, courses, registrations.
- You might be querying data or pushing data in.
Regardless, all Bright API calls function in the same way. Fundamentally, the Bright API is a RESTful API, so much of what is covered here should seem familiar if you’ve worked with a RESTful API before. If not, you may want to familiarize yourself with the concepts here: https://en.wikipedia.org/wiki/Representational_state_transfer .
Source: Wikipedia
2.1. RESTful API #
The Restful api of bright is built around our main resource types:
- Bright Api Keys (/bright/api/v2/api_key)
- Course Provider (/bright/api/v2/course_provider)
- Courses (/bright/api/v2/course)
- Custom Endpoints (/bright/api/v2/customer/…)
- Invitations (/bright/api/v2/invitation)
- Launch Histories (/bright/api/v2/launch_history)
- Realm User (/bright/api/v2/realm_user)
- Registrations (/bright/api/v2/registation)
- Stored Queries (/bright/api/v2/template)
- Templates (/bright/api/v2/template)
for each resource type, we follow the following model, where a specific path, http verb and action are consistent depending on the bright resource you are accessing.
| HTTP Verb | Path | action | used for |
|---|---|---|---|
| GET | /{{resource}} | index | display a list of all {{resource}} [Note: Bright does not implement this canonical REST action]. |
| GET | /{{resource}}/new | new | return an HTML form for creating a new {{resource}} |
| POST | /{{resource}} | create | create a new {{resource}} |
| GET | /{{resource}}/gcreate | create | create a new {{resource}} with a GET request. This is an alias to the POST get request provided to allow the {{resource} to be created from a web browser without using a POST. A variety of cross-domain scripting issues can be addressed using the GET create alias (gcreate). |
| GET | /{{resource}}/:id | show | display a specific {{resource}} |
| GET | /{{resource}}/:id/edit | edit | return an HTML form for editing a {{resource}} |
| PUT | /{{resource}}/:id | update | update a specific {{resource}} |
| GET | /{{resource}}/gupdate/:id | update | update a specific {{resource}} via a GET request. See the comment on gcreate above. |
| DELETE | /{{resource}}/:id | destroy | delete a specific {{resource}} |
2.1.1. Determining your :id for create and update #
Depending on which model you are accessing, the :id record can be specified differently.
When Bright is used to connect with an external course provider (like SCORMCloud), the course provider generated guid can be used for :id. Bright is not strongly tied to any particular course provider, and thus use the following naming convention for external course providers ids:
- registration_guid - this is the ID of a registration in the external course provider
- course_guid - this is the ID of the course in the external course provider
Because Bright considers courses to be provided by a ‘course provider’, you will see fields returned by the Bright API with names like:
- provider_completed_at
- provider_accessed_at
- provider_error_message
etc. This is an indication that the data is not generated by Bright, but from the external course provider.
Please see the API documentuntation for a particular module to see information on how to correctly specify the :id field.
See the registration section for an example.
2.2. List of Available Resources #
- Bright Api Keys (/bright/api/v2/api_key)
- Course Provider (/bright/api/v2/course_provider)
- Courses (/bright/api/v2/course)
- Custom Endpoints (/bright/api/v2/customer/…)
- Invitations (/bright/api/v2/invitation)
- Launch Histories (/bright/api/v2/launch_history)
- Realm User (/bright/api/v2/realm_user)
- Registrations (/bright/api/v2/registation)
- Stored Queries (/bright/api/v2/template)
- Templates (/bright/api/v2/template)
2.3. Special Considerations for Cross-Browser Scripting Restrictions #
One thing about the RESTFul architecture is does not interoperate well with cross browser scripting restrictions in modern browsers. Specifically, you are probably aware that you can not POST or PUT data via JSONP which means you can interact with a pure RESTFul API from a web page delivered from a web server other the one hosting the Bright API.
To alleviate this problem, we provide two “GET”-oriented aliases, gcreate and gupdate, that work identically to create and update, and are available via HTTP GET calls.