Introduction to the Brillium Web API

Introduction

The Brillium Web API allows the query and retrieve the Brillium data (accounts, assessments, respondents, etc.) accessible.   The API is based on REST principles and is described in detail within this technical guide.

Request and Response Pagination

When making a request (GET) to any API call that will return more than one result, the Brillium API allows you to specify the page and page size of the results you would like to receive. You may specify the page and page size on the QueryString. The page parameter is 1-based, and there is no page zero (0).

{brillium_base_uri}/api/Accounts?page=2&pagesize=100

In the example above, we are requesting the second page of 100 records, which would return the records numbered 101-200 using the default sort for accounts (by Account ID).

HTTP GET Method Response Codes

When performing an HTTP GET request against one of the API URI’s, Brillium will return one of the following response codes.

• 200 (OK) – The request was successful. The response body contains the requested data.
• 401 (UNAUTHORIZED) – The Authorization HTTP header was either not found or did not include valid credentials.  Make sure you have enabled the API, built the Authorization token properly, and included it in the HTTP header for the request. 
• 404 (NOT FOUND) – Either the URI you are making the request to is not valid or the data you are asking for does not exist.
• 429 (TOO MANY REQUESTS) – You have made too many calls to the API during a specified time period.  The default limit is 5000 API calls per day.  This resets at midnight in the time zone of the Web server (U.S. Eastern for hosted services).
• 500 (SERVER ERROR) – An error has occurred on the server and your request could not be processed for some reason.  If this persists, contact Brillium technical support. 

Response Format

Brillium will respond to requests in JSON format only

Content-Type: application/json

Below is an example of a JSON response for a single assessment (“MATH101”):

{

  "Assessments": [

    {

      "Id": "MATH101",

      "AccountId": "SUPERSUDS",

      "Name": "Math 101",

      "Password": "******",

      "Anonymous": "No",

      .

      .

      .

      "DateCreated": "2008-11-03T14:14:00-05:00",

      "DateModified": "2008-11-03T17:15:34-05:00",

      "Uri": "http:\/\/supersuds.brillium.com\/api\/Assessments\/MATH101",

      "RelatedUris": {

        "QuestionGroups": 

        "http:\/\/supersuds.brillium.com\/api\/Assessments\/MATH101\/QuestionGroups",

        "Questions": 

        "http:\/\/supersuds.brillium.com\/api\/Assessments\/MATH101\/Questions",

        .

        .

        .

      }

    }

  ],

  "Page": 1,

  "PageSize": 50,

  "TotalCount": 1,

  "HasMore": false

}

Response Wrapper

In the sample above you may notice that there is a JSON “wrapper” around the requested result object. This wrapper will be present with all API calls. It is there to simplify pagination of the results provided by the API. The wrapper looks like this:

{

  "<Items>": [{}],

  "Page": 1,

  "PageSize": 50,

  "TotalCount": 123,

  "HasMore": true

}

Wrapper Field Definitions

• “<Items>” - Refers to the type of objects being requested. In other words, it won’t actually say “<Items>”, but would rather say “Assessments” (always pluralized) for an API call that returns Assessments.
• “Page” – The current page number of the results that are being returned. If you request a page number greater than the total number of pages, you will receive a 404 (NOT FOUND) response.
• “PageSize” – The page size of the results in the response. This defaults to 50 if no page size is included in the request. The maximum page size you may request is 1000.
• “TotalCount” – The total number of results available for the request. If this number returns 123 and you have a page size of 50, there will be 3 pages of results (page 1 will contain 50 results, page 2 will contain 50 results, and page 3 will contain 23 results).
• “HasMore” – This is a Boolean indicating whether there are more pages of results beyond the one you have requested. True means there is at least one more page of results. False means there are no further pages of results.

Response Date Format

All dates and times sent from Brillium are in the Web server’s local time zone.  For hosted clients, this will be the U.S. Eastern Time Zone (New York/Boston).  For server license customers, this will be the time zone specified within the operating system for your Web server.

It is also important to note that Brillium will send back date/time values using the ISO 8601 international standard (http://en.wikipedia.org/wiki/ISO_8601) with UTC time offset.

Sample Date: 2020-11-03T14:14:00-05:00
Represents: November 3, 2020 2:14 PM (U.S. Eastern)