Abstract lens flare, blueprint pattern, keyboard pattern

Builder API

REST API for Developers

Introduction

The Builder API is a REST based API. The API provides access to several different resources via their resource URLs. Each resource URL accept various parameters to query the resource to find specific sets of resources and data. The API also accepts output format parameters to determine the content type of the output it will provide. The API is read-only and doesn't accept PUT requests or allow data to be changed. It is most useful for transporting data from a Builder instance into another system for processing.

Blueprint with ruler and wrench icon.

Authentication

All requests to the API must be authenticated via the Builder instance's API Key. Any un-authenticated requests will be denied. In order to get started with authenticated requests you will need to first Acquire or Set the Builder API Key. Then you will need to include the API Key in the apiKey parameter of your request.

Acquire or Set the Builder API Key

The Builder API Key can be retrieved or changed in the Admin Control Panel at the following path:

Admin / Globals / Builder API

Note: Changing the API Key can break any integrations that have not been updated to use the new key.

Screenshot of Globals > Builder API Key screen

API Key Request Parameter

You can authenticate your request by passing the Builder API Key that was previously set or retrieved in the apiKey parameter of the request URL.

Here is an example request to the directory resource where the apiKey is pJnrpGsE67BF2T645vSRgY6yGU: 

https://example.psu.edu/api/directory?apiKey=pJnrpGsE67BF2T645vSRgY6yGU
Blueprint with ruler and wrench icon.

Resources

There are several resources you can query in the Builder API. All resources require authentication and support several optional query parameters. The supported resources are:

  • Enrollments
  • Courses
  • Terms
  • Directory

See the resource description, parameters, and example code below for each of the resources.

Request Parameters

Each resources accepts different query parameters to search and filter data from the resource, however, there are common request parameters shared between all resources.

  • format - sets the output format of the returned response (string)
    • Options ( application/json - output in JSON ) , ( text/csv - output in CSV )
  • page - sets the page of the results to return
    • Will return empty data when non-existant page. First page is always 1 ( ie: &page=1 )

Response Data

The response data return differs based on the format parameter.

JSON Response Data

The general structure of each is outline below:

  • params : Request parameters submitted and default parameter values
  • data : Response data returned from request
  • pagination : Pagination meta data
  • links: API response navigation links
{
 "params": {
 ...
 "format": "application\/json",
 "page": 1
 },
 "data": [
 {
 "id": 198793,
 ...
 },
 {
 "id": 198077,
 ...
 },
 ...
 ],
 "pagination": {
 "pageSize": 100,
 "totalPages": 1,
 "totalResults": 9
 },
 "links": {
 "self": "https:\/\/websitebuilder.creativeservices.psu.edu\/api\/enrollments?apiKey=I2lYJAGgoAut2PQ6iCetAD2Jjw&format=application%2Fjson&page=1"
 }
}

CSV Response Data

Standard text/CSV data is all that is outputted in the response. You can check for more results by going to the next page. IE: &page=2 

id, title, fielda, fieldb, fieldc
1, "The title", foo, bar, baz
Blueprint with ruler and wrench icon.

Enrollments

The enrollments resource represents the records of the students and the courses they are enrolled in. The enrollments resource is available at:

/api/enrollments

Query Parameters

The following query parameters are accepted for the enrollments resource:

  • courseId - query enrollments by course id (integer)
  • termId - query enrollments by term id (integer)
  • status - query enrollments by completed status (boolean : 1 = completed ; 0 = not completed )
  • startDate - query enrollments with a completed_date after startDate ( date : YYYY-MM-DD )
  • endDate - query enrollments with a completed_date before endDate ( date : YYYY-MM-DD )

Note on startDate and endDate: endDate will be ignored if no startDate is present. If startDate is present but no endDate is specified endDate will be set to startDate +1 day.

Sample Enrollments Requests

Following are examples of requests to the enrollments resource:

All Enrollments

https://builderexample.psu.edu/api/enrollments?apiKey=pJnrpGsE67BF2T645vSRgY6yGU&format=text/csv

All Enrollments for a specific Course

https://builderexample.psu.edu/api/enrollments?apiKey=pJnrpGsE67BF2T645vSRgY6yGU&courseId=198763&format=text/csv

All Enrollments for a specific Course and specific Completed Date Range (1 month)

https://builderexample.psu.edu/api/enrollments?apiKey=pJnrpGsE67BF2T645vSRgY6yGU&courseId=198763&format=text/csv&startDate=2024-08-01&endDate=2024-09-01

Response Data

The following lists the field names, descriptions, and types that are returned for valid requests.

  • id - internal id of the enrollment record (integer)
  • enrollment - unique id hash for enrollment record (uuid)
  • active - whether the enrollment is currently active (boolean)
  • user_email - email of the user enrolled in the course (string)
  • user_name - username of the user enrolled in the course (string)
  • user_firstname - first name of the user enrolled in the course (string)
  • user_lastname - last name of the user enrolled in the course (string)
  • course - name of the course the user is enrolled in (string)
  • course_id - internal id of the course the user is enrolled in (integer)
  • term - the term of the course the user is enrolled (string)
  • term_id - internal id of the term of the enrollment
  • completed - whether the user completed the enrolled course (boolean)
  • completed_date - the date the user completed the enrolled course (date)

Sample Response Data (JSON) [ data: element ]

[
 {
 "id": 198793,
 "enrollment": "492f5275-1f88-4076-942b-d2c9989d87a9",
 "active": true,
 "user_email": "tjw218@psu.edu",
 "user_name": "tjw218",
 "user_firstname": "Tyler",
 "user_lastname": "Wilkinson",
 "course": "Test Course",
 "course_id": 198763,
 "term": "2024-2025",
 "term_id": 181854,
 "completed": true,
 "completed_date": "2024-11-26"
 }
]

Sample Response Data (CSV)

id,enrollment,active,user_email,user_name,user_firstname,user_lastname,course,course_id,term,term_id,completed,completed_date
198793,492f5275-1f88-4076-942b-d2c9989d87a9,1,tjw218@psu.edu,tjw218,Tyler,Wilkinson,"Test Course",198763,2024-2025,181854,1,2024-11-26
Blueprint with ruler and wrench icon.

Courses

The courses resource represents the records of the courses available in the builder instance. The courses resource is available at:

/api/courses

Query Parameters

  • courseId - Query by a single course id (integer)

Sample Courses Requests

Following are examples of requests to the course resource:

All Courses

https://builderexample.psu.edu/api/courses?apiKey=pJnrpGsE67BF2T645vSRgY6yGU&format=application/json

Specific Course (by courseId)

https://builderexample.psu.edu/api/courses?apiKey=pJnrpGsE67BF2T645vSRgY6yGU&courseId=123456&format=application/json

Response Data

The following lists the field names, descriptions, and types that are returned for valid requests.

  • id - internal id of the course record (integer)
  • title - descriptive title of the course (string)
  • enabled - whether the course is currently enabled (boolean)
  • url - website url to access the course (string)
  • term - the term name assigned to the course (string)
  • term_id - internal id of the term currently assgined to the course (integer)

Sample Response Data (JSON)

[
 {
 "id": 147011,
 "title": "Course 101",
 "enabled": true,
 "url": "https:\/\/builderexample.psu.edu\/courses\/course-101",
 "term": "2024-2025",
 "term_id": 181854
 },
 {
 "id": 198763,
 "title": "Test Course",
 "enabled": true,
 "url": "https:\/\/builderexample.psu.edu\/courses\/test-course",
 "term": "2024-2025",
 "term_id": 181854
 }
]

Sample Response Data (CSV)

id,title,enabled,url,term,term_id
147011,"Course 101",1,https://builderexample.psu.edu/courses/course-101,2024-2025,181854
198763,"Test Course",1,https://websitebuilder.psu.edu/courses/test-course,2024-2025,181854
Blueprint with ruler and wrench icon.

Terms

The terms resource represents the records of the terms available in the builder instance. The terms resource is available at:

/api/terms

Query Parameters

  • termId - internal id of the term record (integer)

Sample Terms Requests

Following are examples of requests to the course resource:

All Terms

https://builderexample.psu.edu/api/terms?apiKey=pJnrpGsE67BF2T645vSRgY6yGU&format=application/json

Specific Term ( by termId )

https://builderexample.psu.edu/api/terms?apiKey=pJnrpGsE67BF2T645vSRgY6yGU&termId=12345&format=application/json

Response Data

The following lists the field names, descriptions, and types that are returned for valid requests.

  • id - internal id of the term record (integer)
  • title - the descriptive title of the term record (string)
  • start_date - date to hint at the term start date (date : YYYY-MM-DD)
  • end_date - date to hint at the term end date (date : YYYY-MM-DD)

Note: start_date and end_date are merely descriptions of when the term is to be used. An administrator will still be responsible for enabling , disabling , changing course terms.

Sample Response Data (JSON)

[
 {
 "id": 185383,
 "title": "Current",
 "start_date": "2024-10-01",
 "end_date": ""
 },
 {
 "id": 181854,
 "title": "2024-2025",
 "start_date": "2024-07-18",
 "end_date": "2025-06-28"
 }
]

Sample Response Data (CSV)

id,title,start_date,end_date
185383,Current,2024-10-01,
181854,2024-2025,2024-07-18,2025-06-28
Blueprint with ruler and wrench icon.

Directory

The directory resource represents the records of the people ( faculty / staff ) from the directory listing. The directory resource is available:

/api/directory

Query Parameters

  • directoryId - internal id of the directory entry ( integer )
  • psuId - Penn State User ID of the directory entry (string)
  • firstName - first name of the directory entry
  • lastName - last name of the directory entry

Sample Directory Requests

The following are examples of requests to the directory resource

All Directory Entries

https://builderexample.psu.edu/api/directory?apiKey=pJnrpGsE67BF2T645vSRgY6yGU&format=application/json

Specific Directory Entry ( by psuId )

https://builderexample.psu.edu/api/terms?apiKey=pJnrpGsE67BF2T645vSRgY6yGU&format=application/json&psuId=xyz123

Response Data

The following lists the field names, descriptions, and types that are returned for valid requests

  • id - internal id of the directory record (integer)
  • url - website url to the directory entry
  • firstName - first name of the person in the directory entry
  • middleName - miiddle name of the person in the directory entry
  • lastName - last name of the person in the directory entry
  • psuId - the Penn State User ID of the person in the directory entry

Sample Response Data (JSON)

[
 {
 "id": 184268,
 "url": "https:\/\/websitebuilder.creativeservices.psu.edu\/directory\/test-hypen-doe",
 "firstName": "Test-Hypen",
 "middleName": "",
 "lastName": "Doe",
 "psuId": ""
 },
 {
 "id": 115063,
 "url": "https:\/\/websitebuilder.creativeservices.psu.edu\/directory\/testing-tester",
 "firstName": "Testing Expert",
 "middleName": "",
 "lastName": "Tester",
 "psuId": ""
 }
]

Sample Response Data (CSV)

id,url,firstName,middleName,lastName,psuId
184268,https://websitebuilder.creativeservices.psu.edu/directory/test-hypen-doe,Test-Hypen,,Doe,
115063,https://websitebuilder.creativeservices.psu.edu/directory/testing-tester,"Testing Expert",,Tester,
Blueprint with ruler and wrench icon.

Contact

If you are interested in using the Builder API for your project or website please contact us using the link below.

Client Questionaire