The following are frequently asked questions from our member campuses and specifically application programmers who work with the API. If you have a question that is not addressed below, please contact Engage Support (firstname.lastname@example.org) and a representative will be happy assist you. Questions and answers specific to individual resources available from the API are included in their respective documentation pages.
What can you do with the API?
Lots of things! The API is basically a way for you to pull data out of Engage automatically and either share it with other campus applications or store your own copy of it in a database at your institution. Either way, the information your system is collecting on co-curricular activities can be leveraged to create even more value than when it is kept inside Engage alone.
Do I need a programmer to use it?
Yes, you will need a web developer, application programmer, or someone reasonably familiar with writing code. Additionally, this person or persons will need a server upon which to store and run their code, and potentially a database in which to save data--depending on what you are using the API for.
Who on my campus has access to the data?
Using the API requires Engage support staff to create a public/private key pair. These are somewhat like a username and password for connecting to the API. We will take request for these key pairs to be created from a person known as a primary contact for us at the institution, or to someone the primary contact designates. Key pairs can be restricted to certain types of data, or given access to all types of data. Typically, we do not recommend you grant usage of the API to anyone other than a campus administrator who would otherwise have access to the same data were he/she logged directly into the system.
Does my license include the API?
The API may or may not be included in your institutional license for Engage and/or other Campus Labs products. Please contact your Campus Relations representative or contact Engage Support (email@example.com) to inquire further.
Should I use XML or JSON?
I'm getting an Unauthorized (401) error. Why can’t I authenticate?
If you refer to the documentation on Connecting to the API, you will see that there are several "points of failure" possible when you write your code for connecting to and authenticating with the API.
- First you should verify that you are using the correct public and private key pair information. If you wish to verify your key pair details, please contact Engage Support (firstname.lastname@example.org).
- You will also want to ensure that access has been enabled for the type of data you are attempting to pull from the API.
- Your requests may be outside the time expiration window. It is often the case that developers have mistaken converted the current time to something other than milliseconds (which should have 13 digits) or that the time value upon which the developer bases his/her calculation is slightly off (i.e., the web server's CPU clock isn't synchronized to a time server) from the API's clock.
- You may not have properly constructed your hash value. It should be the encrypted form of a concatenated string created from your public key value, your IP address (if you have IP restriction enabled), current time in milliseconds, your random string, and your private key value. Please note that the order of characters in a string that has a hashing algorithm applied to it DOES MATTER as evidenced below:
MD5("ABC") = 902fbdd2b1df0c4f70b4a5d23525e932
MD5("CBA") = a61a40943e07257e084ea3f62dfdb1c8
- If you asked Engage staff to enable IP address restriction on your key pair, but are either running code from a server that does not match the given IP address or you have forgotten to include the IP address in your hash value (if included, it goes after the time).
I have to make iterative calls across multiple end-points to join together information. Wouldn't it be more efficiency to just combine some of this data into one feed?
In the design of Version 2.0 of the API, we attempted to anticipate the needs of campus developers related to combining together data. This resulted in the addition of critical "join" IDs in each endpoint. For example, when you are returning a list of events in the system, you are supplied with the ID of the organization that created each event. If you wanted the URL of the organization alongside the data for a given event sponsored by that organization, you would have to make a separate call to the /organizations endpoint in order to retrieve that URL. A question often asked by developers is why (as one example) we don't just put the organization's URL in the feed of data returned by the /events endpoint.
This question is valid and representative of what is often thought of as the N+1 problem; that is, it's typically thought to be more efficient to run a single query that returns a given number of records than it is to run that query one time for each record that eventually adds to the total given number. While from a code performance perspective this N+1 is usually something to be avoided, the case of an API is a little different. By their very nature, APIs are typically built to withstand LOTS of individual calls that go back and forth to the database to retrieve relatively small amounts of information for you. For a typical API, the overhead incurred in an N+1 scenario isn't as bad as the overhead that comes with really large or complex queries (i.e., queries that must join together lots of data from multiple tables across the database). In short, while from a coding perspective it might appear more efficient to put as much relevant data into one feed as possible, from a performance perspective it is far better for the API to limit each endpoint to a single domain (i.e., just event data or just organization data) as often as it can. The Engage API does sometimes break this convention by supplying more than just an ID for related data on a given endpoint (e.g., you might see the organization's name as well as its ID on the call for a list of events), but in general we strive to avoid over-doing it by adding too many of such related fields that come from different parts of the database.
It should be noted that in there are some circumstances wherein a developer can avoid the N+1 problem by writing code in a way that relies on the power of institution server resources. For example, imagine an institution that was using the API to extract a list of organizations in order to feed those into a student information system and then also wanted to extract a list of events to feed into a campus calendar application. Similar to the situation described earlier, imagine this campus wanted the URL of each organization to go along with each event pulled from the /events endpoint. The institution's code might first take care of calling the organization data, then it might go into a routine for the event data. This is where the developer of this code might think he or she has to make additional calls out to /organization for each entry in /events in order to get the sponsoring organization's URL. However, if when originally calling the organization data the developer had stored that information in an array (i.e., using the memory of the server from which the code was run) or even in a local database table, then that information could be easily re-accessed without the need to make additional calls back to the Engage API. This hypothetical scenario may not always apply to your needs, but hopefully it points out that if your goal is speed and efficiency, you should be creative in thinking about how you write your code for the API to handle the data you retrieve.