Table of Contents
Overview
Use Cases
Creating a Read-Only API User
Creating a Read & Write API User
API Support
Related Articles
Overview
Coursedog offers an API for schools that are looking to use Coursedog data to create a datalake, custom reports, or custom applications.
The solution for this can be to create a “read-only API user” (recommended) or a “read and write API user”. Note we don’t recommend “read and write API users” except in very specific/limited use cases.
Use Cases
Creating an API user – specifically a Read-Only API User – can come in handy in the following scenarios:
If you need a report of all of your faculty’s names, emails, and teaching load this term, you could use our Professors API to generate it.
You need to pull data into a centralized data lake and run reports.
Creating a Read-Only API User
Overview | How to Do It | Read-Only User Restrictions | Additional Notes
Overview
In most cases, the solution to accessing the Coursedog API is to create a read-only API user in staging or production.
API users are used by schools who want to programmatically retrieve data in bulk.
A read-only API user will allow the user to hit Coursedog’s API to access and read data, but it will prevent that user from overwriting any data in the application.
Because it is a read-only function that will not disrupt the main application, a read-only user can be created in production directly rather than needing to test in staging.
How to Do It
Step 1:
Reach out to your Coursedog Project Manager (PM) or Customer Success Manager (CSM) – whichever one is your current contact – to inquire about the API with your use case.
Once confirmed this route will work for you, the Coursedog product team can turn on a feature flag for the Read Only API that will enable you to create a “read only API user”.
Once the feature flag is turned on, a “Read Only API User” option will appear on the “Add New User” modal (shown below).
Step 2:
Navigate to Settings > Users and click “+ Add User”.
Learn more about adding new users here.
Step 3: You can make the first name and last name of the API user anything you want, but we recommend assigning a First Name of “Read Only” and a Last Name of “API User”.
Step 4:
For the email address, this can be any email address that’s not already assigned to a Coursedog user.
We recommend api-user@[schoolname].edu.
Step 5: Click the login method field and select “password” as the option, rather than default or SSO based login. If you use a default or SSO based login, your user will not be able to read the API.
Step 6: Select “YES” under “Read Only API User” at the bottom of the modal.
Step 7: Click “Add Without Sending Mail” at the bottom of the modal to create a new read-only API user.
Read-Only User Restrictions
Read-only users will have the following restrictions:
For all authenticated endpoints, the user will only be able to perform GET operations.
This means all PUT/POST/DELETE operations will be rejected by this user. All public POST endpoints (such as generating a session for authentication) will still be available.
Additional Notes
This MUST be only used for API users. If such a user tries to log in to the UI, they will experience issues within the application, as the application expects all users to have some ability to execute POSTs.
Once the user is created, the user can read the Coursedog API using the following authentication documentation: https://coursedog.docs.apiary.io/. The documentation provides details on how the Read Only API User can access the Coursedog API.
Creating a Read & Write API User
Overview
In general, we advise against creating a Read & Write API user unless your institution has a need to populate data into the Coursedog application.
Some use cases for read & write API users are institutions with homegrown SISs that are building an in-house API integration with the Coursedog application.
How to Do It
To create a Read & Write API user, we would recommend first testing in a staging environment.
You can create this user in the user modal following the steps outlined above under “Creating a Read-Only API User” (including the addition of a valid email address) but note the following:
We recommend First Name be “Read and Write” and Last Name be “API User”.
Do NOT select anything for “Read Only API User” – keep this setting blank.
In general, the role-based permissions that you assign to the user will correspond to the permissions that the user has to write to the API. Consequently, we strongly recommend you create a separate custom role for the Read & Write API User and make it as restrictive as possible (this will allow you to limit which areas they are able to read/write).
That said, not everything is controlled by role permissions (data that should be accessible to all logged-in users) including some writes.
That is part of why we recommend only providing read/write access in very limited use cases, that are tested thoroughly in staging first.
API Support
While Coursedog provides an API free of charge to our institutional partners, we do not provide engineering support to API-based use cases. However, an institution that wishes to receive support on API use cases may reach out to their PM or CSM about submitting a change request in order to procure a bucket of support hours.