API 1.0 | HelioCampus Assessment Management Knowledge Base

On This Page	Introduction API 1.0 Setup API Usage URL Format, Data Format, and Pagination Sample API Calls Retrieve the list of all departments: Retrieve the list of courses: Retrieve the details of a single course: Retrieve the list of course sections: Faculty Portfolio Details Course and Course Section Syllabus Details API v.1.0 Endpoints

Introduction

Our Application Programming Interface (API) provides access to your assessment platform data for use in other applications. API supports main business objects such as program outcomes, course outcomes, course syllabus, assessment results, survey results, and others, and continues to expand with new functionality and additional use-cases.

This documentation provides the basic information for the API and aims to give a quick start. For additional information and use of the API for a specific use-case, please contact mailto:support@heliocampus.com. Once your institution is configured to use the API, you can use the <institution url>/api URL for documentation and a sandbox environment for the API.

API v1.0 supports only data read and supports GET operations only and returns structured JSON data.

API supports access to all the main business objects within the platform. Using the API, you can:

Get lists of business objects
Send search/filter parameters to get to the right data set
Scroll through the result set to get all the items in the data set
Get details on the object using an object identifier returned by the platform
Pull report data from the platform

API 1.0 Setup

API 1.0 supports two authentication methods to access the API;

Basic Authentication

HelioCampus provides an API key and secret for your institution through a secure channel. Safeguard your API key and secret. The API connection mandates TLS 1.2 encryption. Encode your key and password using the base 64 algorithm and include it in the header named "Authorization" with the prefix "Basic".

Keycloak Authentication

To use this method, a user account must first be created at the Assessment Platform. You can easily create a user by following the instructions provided here: Create a User Account. The roles and permissions assigned to this user are crucial, as the API will return data based on the requester's roles and permissions.

The HelioCampus Assessment Platform leverages Keycloak for identity and access management. To obtain a JSON Web Token (JWT) for API access, use the following command:

curl --location 'https://keycloak.heliocampus.net/auth/realms/<realm name>/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=aefis-services-public' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'scope=aefis' \
--data-urlencode 'username=<email or username information>' \
--data-urlencode 'password=<password information>'

Your institution’s realm name will be securely provided by HelioCampus. Upon making this POST request, you will receive a response containing an "access_token," which serves as the JWT for API access.

Here is an example of a returned JWT:

{
    "access_token": "...",
    "expires_in": 299,
    "refresh_expires_in": 1799,
    "refresh_token": "...",
    "token_type": "Bearer",
    "not-before-policy": 0000000000,
    "session_state": "0000000-0000-0000-0000-0000000000",
    "scope": "profile aefis email"
}

Include this token in the headers of your API requests by using the "Authorization" field with the "Bearer" prefix:

curl --location 'https://<heliocampus-url>/api/colleges' \
--header 'Authorization: Bearer <access_token>'

By following this method, the requester's identity is clearly established. The JWT passed to the Assessment Platform enables seamless identification and enforces access controls based on the user’s assigned roles and permissions within the system. As a result of the API call, the application should return the requested data with a 200 status code.

API Usage

API calls require a basic authentication authorization header as part of the GET request. Data will be returned in JSON format.

The number of records returned from the API call will be limited by the API and unless a maxResults parameter is specified, the results returned in a single call might be incomplete. The client is responsible to use the start parameter to receive the rest of the data from the API.

List APIs contains general-purpose optional parameters. The filter parameter is designed to maintain flexible and composite filtering on relational data.

Sample API Calls

Attention: Samples are given without URL encoding to maintain readability. Actual calls require these strings to be URL encoded.

Retrieve list of all colleges:

https://<aefis-url>/api/colleges

Optional Parameters:

start	Starting position for the listing (can be used for paging)
maxResults	Integer (default to 50). Maximum number of results returned
sortOrder	Determines the order of results returned

Retrieve the list of all departments:

https://<aefis-url>/api/departments

Optional Parameters:

filter	Example usage of filter: filtering by id of the college `filter={'College.Id'=<collegeId>}` filtering by code `filter={'Code'='<code>'}`
start	Starting position for the listing (can be used for paging)
maxResults	Integer (default to 50). Maximum number of results returned
sortOrder	Determines the order of results returned

Retrieve the list of courses:

https://<aefis-url>/api/courses

Optional Parameters:

filter	Example usage of filter: composite filtering example `filter={'Department.College.Id'=<collegeId>,'Department.Id'=<departmentId>}` filtering by CourseUniqueId `filter={'CourseUniqueId'='<CourseUniqueId>'}`
start	Starting position for the listing (can be used for paging)
maxResults	Integer (default to 20). Maximum number of results returned
sortOrder	Determines the order of results returned

Retrieve the details of a single course:

https://<aefis-url>/api/v1/courses/

Required Parameters:

courseId

Numeric Identifier (should be retrieved using the API) of the course

Retrieve the list of course sections:

https://<aefis-url>/api/coursesections

Optional Parameters:

filter	Example usage of filter: composite filtering example `filter={'Term.Name'='<termName>','Course.Id'=<courseId>}` filtering by CourseSectionUniqueId `filter={'CourseSectionUniqueId'='<CourseSectionUniqueId>'}`
start	Starting position for the listing (can be used for paging)
maxResults	Integer (default to 50). Maximum number of results returned
sortOrder	Determines the order of results returned

Faculty Portfolio Details

The API Faulty Portfolio endpoints have been extended to provide additional details on the faculty portfolio information.

To receive ParentCategoryCode list:
<your institution url>/facultyPortfolio/parentCategoryCode/

You can use 'all' keyword to receive all activities for a faculty portfolio:
<your institution url>/facultyPortfolio/220/serviceActivity/all

You can separate use comma separated list to receive multiple categories:
<your institution url>/facultyPortfolio/220/serviceActivity/code1,code2

Course and Course Section Syllabus Details

API Course/Course Section Syllabus have been provided for external information.

To receive Course Syllabus information:

<your institution url>/courses/{courseId}/syllabus/

And very similar to Course, to receive Course Section Syllabus information:

<your institution url>/coursesections/{coursesectionid}/syllabus/

As an example for Course:

You can also get form item (question) answers individually providing their codes in “query string parameters” section. As a sample way, take this syllabus form: