HelioCampus Assessment (AEFIS) needs a specific SIS dataset for implementation (see Data Integration Specification) and can receive this data through a REST API. This document defines the requirements for creating such an API.
This documentation describes the API format and provides samples.
Data Connector REST API
Data Connector REST API needs to provide access to all the SIS records that will be imported to the Assessment Platform.
Using the API, the data connector should be able to:
-
Get the list of records
-
Page through the records to get all the items in the dataset
Security
Authentication
Data Connector API supports different authentication methods for accessing the end point. OAuth2 is the recommended method for authentication but basic authentication can also be used for simplicity.
SSL
Rest API should be hosted in an SSL environment and accessed via https url explicitly. Since security data will be sent in the https headers (or body) any non-encrypted connection will not provide the necessary security.
Data Connector API URL Format
Data Connector API calls require the parameters below in the GET request. Security-related parameters will be sent in the HTTP Headers. The suggested authentication method is OAuth2, in which case, the Bearer Token will be sent in the HTTP Authorization Header.
Return type :
Any successful API call should return an HTTP 200 status code and a payload of data in JSON format.
Any unsuccessful call should return the appropriate HTTP 4xx or 5xx status code. If an error status is returned, error description should be returned in JSON format in the body.
Required URLs :
Below end points must be supported in order to provide the minimum necessary SIS data set:
https://[application_url]/activeterms
https://[application_url]/course
https://[application_url]/coursesection/{{termcode}}
https://[application_url]/registration/{{termcode}}
https://[application_url]/faculty
https://[application_url]/degree/{{termcode}}
https://[application_url]/student
Flow:
In order for imports to work; the data should work within a single term. Thus, first API call will be made to activeterms to receive currently active term’s codes. The code values will be used to limit the data for coursesection, registration and degree. If needed, course, faculty and student endpoints can also support termcode parameters.
Pagination :
In order for pagination to work correctly
-
A default sort order should be guaranteed. API implementation can select an arbitrary sort field.
-
There should be no overlapping records in consecutive pages.
-
Link headers should be provided
Parameters :
offset: Number of records to skip, default is 0
limit: Page size, default is suggested to be 50
Paging parameters will be sent using URL query strings. For example to get a list of first 50 courses URL should be:
https://[application_url]/course?offset=0&limit=50
Paging Information:
HTTP Link Header will be used by the API provider to return information about record paging. With each call, the API should return the below paging information as appropriate. Returned headers should provide the absolute URLs that include all parameters necessary to retrieve the desired current, next (if exists), previous(if exists), first, and last page.
Pagination information in the Link header:
Link: <https://[application_url]/course?offset=250&limit=50>; rel="current",
<https://[application_url]/course?offset=200&limit=50>; rel="prev",
<https://[application_url]/course?offset=300&limit=50>; rel="next",
<https://[application_url]/course?offset=0&limit=50>; rel="first",
<https://[application_url]/course?offset=500&limit=50>; rel="last"
These links will only be included if they are relevant. For example, the first page of results will not contain a rel="prev" link. rel="last" may also be excluded if the total count is too expensive to compute on each request.
Using the above information Data Connector can call the REST API using the form:
curl -H "Authorization: Bearer [OAuth2-Bearer-Token]" "https://[application_url]/course?offset=150&limit=50"
The example above would return 50 courses skipping the first 150 of them.
Sample API Calls
The data samples provided show the required dataset. Optional data fields can be added to the records in a similar fashion.
-
Receive list of active terms:
curl -H "Authorization: Bearer [OAuth2-Bearer-Token]" "https://[application_url]/activeterms?offset=150&limit=50"
This should return a result similar to below example: (See Data Integration Specification for required, optional fields and field types for all objects)
HTTP/1.1 200 OK
[... omitted headers for clarity ...]
Link: <https://[application_url]/activeterms?offset=150&limit=50>; rel="current", <https://[application_url]/activeterms?offset=100&limit=50>; rel="prev", <https://[application_url]/activeterms?offset=200&limit=50>; rel="next", <https://[application_url]/activeterms?offset=0&limit=50>; rel="first", <https://[application_url]/activeterms?offset=350&limit=50>; rel="last"
[... omitted headers for clarity ...]
[
{
"Code": "2021Spring",
"Name": "2021 Spring Semester"
},
{
"Code": "2021Fall",
"Name": "2021 Fall Semester"
}
]
-
Receive list of all courses:
curl -H "Authorization: Bearer [OAuth2-Bearer-Token]" "https://[application_url]/course?offset=150&limit=50"
This should return a result similar to below example: (See Data Integration Specification for required, optional fields and field types for all objects)
HTTP/1.1 200 OK
[... omitted headers for clarity ...]
Link: <https://[application_url]/course?offset=150&limit=50>; rel="current", <https://[application_url]/course?offset=100&limit=50>; rel="prev", <https://[application_url]/course?offset=200&limit=50>; rel="next", <https://[application_url]/course?offset=0&limit=50>; rel="first", <https://[application_url]/course?offset=350&limit=50>; rel="last"
[... omitted headers for clarity ...]
[
{
"CourseUniqueId": "490010239",
"SubjectCode": "CS",
"CourseNumber": "101",
"Title": "Computer Science",
"LongDescription": "Algorithmic Problem Solving",
"CollCode": "CS",
"CollName": "Computer Science",
"DeptCode": "CSCP",
"DeptName": "Computer Programing",
"ProcessDate": "2019-02-20T23:57:48.000Z",
"Credits": 3
},
{
"CourseUniqueId": "490010240",
"SubjectCode": "CS",
"CourseNumber": "201",
"Title": "Computer Science",
"LongDescription": "Algorithmic Problem Solving"
"CollCode": "CS",
"CollName": "Computer Science",
"DeptCode": "CSCP",
"DeptName": "Computer Programing",
"ProcessDate": "2019-02-20T23:57:48.000Z",
"Credits": 3,
"Preq": "CS101, CS102"
}
]
-
Receive list of all course sections:
Termcode filter is required to pull course sections for a specific term.
curl -H "Authorization: Bearer [OAuth2-Bearer-Token]" "https://[application_url]/coursesection?offset=150&limit=50"
This should return a result similar to below example: (See Data Integration Specification for required, optional fields and field types for all objects)
HTTP/1.1 200 OK
[... omitted headers for clarity ...]
Link: <https://[application_url]/coursesection/{{termcode}}?offset=150&limit=50>; rel="current", <https://[application_url]/coursesection/{{termcode}}?offset=100&limit=50>; rel="prev", <https://[application_url]/coursesection/{{termcode}}?offset=200&limit=50>; rel="next", <https://[application_url]/coursesection/{{termcode}}?offset=0&limit=50>; rel="first", <https://[application_url]/coursesection/{{termcode}}?offset=350&limit=50>; rel="last"
[... omitted headers for clarity ...]
[
{
"CourseSectionUniqueId": "23949001",
"CourseUniqueId": "490010239",
"SubjectCode": "CS",
"CourseNumber": "101",
"SectionNumber": "1",
"TermCode": "1124",
"TermDesc": "2018-2019 Summer",
"Title": "Computer Science",
"PrimaryInstrUnivId": "10239",
"ProcessDate": "2019-02-20T23:57:48.000Z",
"ExternalLmsID": 49001
},
{
"CourseSectionUniqueId": "23949002",
"CourseUniqueId": "490010239",
"SubjectCode": "CS",
"CourseNumber": "101",
"SectionNumber": "1",
"TermCode": "1124",
"TermDesc": "2018-2019 Summer",
"Title": "Computer Science",
"PrimaryInstrUnivId": "10240",
"ProcessDate": "2019-02-20T23:57:48.000Z",
"ExternalLmsID": 49002
}
]
-
Receive list of all registrations:
Termcode filter is required to pull registrations for a specific term.
curl -H "Authorization: Bearer [OAuth2-Bearer-Token]" "https://[application_url]/registration?offset=150&limit=50"
This should return a result similar to below example: (See Data Integration Specification for required, optional fields and field types for all objects)
HTTP/1.1 200 OK
[... omitted headers for clarity ...]
Link: <https://[application_url]/registration/{{termcode}}?offset=150&limit=50>; rel="current", <https://[application_url]/registration/{{termcode}}?offset=100&limit=50>; rel="prev", <https://[application_url]/registration/{{termcode}}?offset=200&limit=50>; rel="next", <https://[application_url]/registration/{{termcode}}?offset=0&limit=50>; rel="first", <https://[application_url]/registration/{{termcode}}?offset=350&limit=50>; rel="last"
[... omitted headers for clarity ...]
[
{
"TermCode": "1124",
"StudentUnivId": "2002101879",
"CourseSectionUniqueId": "23949001",
"ProcessDate": "2019-02-20T23:57:48.000Z"
},
{
"TermCode": "1124",
"StudentUnivId": "2002101978",
"CourseSectionUniqueId": "23949001",
"ProcessDate": "2019-02-20T23:57:48.000Z"
}
]
-
Receive list of all faculties:
curl -H "Authorization: Bearer [OAuth2-Bearer-Token]" "https://[application_url]/faculty?offset=150&limit=50"
This should return a resultset similar to below example: (See Data Integration Specification for required, optional fields and field types for all objects)
HTTP/1.1 200 OK
[... omitted headers for clarity ...]
Link: <https://[application_url]/faculty?offset=150&limit=50>; rel="current", <https://[application_url]/faculty?offset=100&limit=50>; rel="prev", <https://[application_url]/faculty?offset=200&limit=50>; rel="next", <https://[application_url]/faculty?offset=0&limit=50>; rel="first", <https://[application_url]/faculty?offset=350&limit=50>; rel="last"
[... omitted headers for clarity ...]
[
{
"UserName": "jd1124",
"FacultyUnivId": "2002101879",
"LastName": "Doe",
"FirstName": "John",
"PrimaryEmail": "jd1124@aefis.university",
"ProcessDate": "2019-02-20T23:57:48.000Z"
},
{
"UserName": "jd1125",
"FacultyUnivId": "2002101978",
"LastName": "Doe",
"FirstName": "Jane",
"PrimaryEmail": "jd1125@aefis.university",
"ProcessDate": "2019-02-20T23:57:48.000Z"
}
]
-
Receive list of all degrees:
Termcode filter is required to pull registrations for a specific term.
curl -H "Authorization: Bearer [OAuth2-Bearer-Token]" "https://[application_url]/degree/{{termcode}}?offset=150&limit=50"
This should return a result similar to below example: (See Data Integration Specification document for required, optional fields and field types for all objects)
HTTP/1.1 200 OK
[... omitted headers for clarity ...]
Link: <https://[application_url]/degree/{{termcode}}?offset=150&limit=50>; rel="current", <https://[application_url]/degree/{{termcode}}?offset=100&limit=50>; rel="prev", <https://[application_url]/degree/{{termcode}}?offset=200&limit=50>; rel="next", <https://[application_url]/degree/{{termcode}}?offset=0&limit=50>; rel="first", <https://[application_url]/degree/{{termcode}}?offset=350&limit=50>; rel="last"
[... omitted headers for clarity ...]
[
{
"ProgramName": "Artificial Intellegence",
"ProgramCode": "AI",
"DepartmentCode": "CS",
"MajorCode": "M_AI",
"CollCode": "ENG",
"ProcessDate": "2019-02-20T23:57:48.000Z"
},
{
"ProgramName": "Data Science",
"ProgramCode": "DS",
"DepartmentCode": "CS",
"MajorCode": "M_DS",
"CollCode": "ENG",
"ProcessDate": "2019-02-20T23:57:48.000Z"
}
]
-
Receive list of all students:
curl -H "Authorization: Bearer [OAuth2-Bearer-Token]" "https://[application_url]/student?offset=150&limit=50"
This should return a result similar to below example: (See Data Integration Specification document for required, optional fields and field types for all objects)
HTTP/1.1 200 OK
[... omitted headers for clarity ...]
Link: <https://[application_url]/student?offset=150&limit=50>; rel="current", <https://[application_url]/student?offset=100&limit=50>; rel="prev", <https://[application_url]/student?offset=200&limit=50>; rel="next", <https://[application_url]/student?offset=0&limit=50>; rel="first", <https://[application_url]/student?offset=350&limit=50>; rel="last"
[... omitted headers for clarity ...]
[
{
"UserName": "jd1124",
"FacultyUnivId": "2002101879",
"LastName": "Student",
"FirstName": "John",
"PrimaryEmail": "js1124@aefis.university",
"ProcessDate": "2019-02-20T23:57:48.000Z"
},
{
"UserName": "jd1125",
"FacultyUnivId": "2002101978",
"LastName": "Student",
"FirstName": "Jane",
"PrimaryEmail": "js1125@aefis.university",
"ProcessDate": "2019-02-20T23:57:48.000Z"
}
]