Some Engage contracts include access to Engage's Application Programming Interface (API). A campus can leverage the API to pull data from Engage and integrate with other systems on campus. API is one of several Data Services options that Engage offers.
What is an API?
APIs are instructions that tell software developers how to program against a web application without needing to know the intricacies (design, technology, methods) of how that application was made. APIs make it possible for users to simultaneously use multiple web applications transparently within the experience of a single application.
For example, when you use a Maps App on your phone to find a coffee shop near you you are using the user interface of the Maps App, but its likely that the app is connecting to at least two, if not more, other applications in order to find your current location, search for coffee shops near that location, grab the images to display the map on the screen, and plotting the exact location of the coffee shops on the map. Each of these data elements may live in different web applications, APIs allow the maker of the Maps App to mix them all together into a singular experience.
APIs allow web applications to focus on the data that they are uniquely designed to collect and manage and then offer their data to developers to mix and re-mix with data from other web applications that have expertise in a different data set.
API Endpoints & Methods
All APIs contain endpoints, which are a general descriptor of the data object that is available to interact with. One of the most popular endpoints in the Engage member API is /events which contains data about organization events.
Each endpoint may have multiple Methods that can be used to interact with the data the endpoint contains. Methods have short names that describe what they do; GET, POST, PUT, and DELETE are the most common. These short names are common across most APIs in the world and are well understood by software developers.
We limit some of the data and interactions that are available via the member API by design to ensure system performance and security. All available endpoints are accessible to a "GET" call (will share data related to the endpoint) but only some endpoints will allow POST, PUT, and/or DELETE calls. You can access additional details about all available endpoints by reviewing your campus' API documentation.
API Security
Most APIs, including the Engage member API, require credentials from campus applications in order to release data or respond at all.
Engage uses a standard method for securing calls to and data from the member API which requires each API user to create a set of credentials that are similar to a username and password called keys. Each set of keys can be configured with a custom mixture of endpoint and method access, which means that a campus application could have multiple keys setup for different reasons.
Accessing the Engage API & Documentation
As of November 2019, Campus Labs currently offers two supported versions of the API, version 2 and version 3. Version 3 is under active development and will continue to be maintained. More endpoints are expected to be added continuously over time. However, some endpoints have not yet been migrated from Version 2 to Version 3. Therefore a campus may need to use two keys concurrently to accomplish various tasks.
Each version has different methods of access and configuration. You cannot use an API v2 key with API v3, or vice versa. Separate keys must be generated for each.
Documentation
To access the detailed API documentation, go to the Admin view of your Engage community. From the Configure menu, choose API Keys. From this page you will find links to both API version 2 and 3 documentation. Version 2 documentation can also be accessed by appending /api/docs to the end of the site's base URL.
- campusdomain.campuslabs.com/engage/api/docs
- vanity.campusdomain.edu/api/docs
Assigning & reviewing keys
Version 2 API keys can only be generated by Campus Labs staff. Contact support for more information (see contact button on this page).
Version 3 API keys can be generated directly by the administrator on the API Keys page. Administrators can also use this page to review currently issued keys and their associated permissions.
Once a key has been shared with a user, that user can review their available keys at any time using the User Drawer. Simply open the user drawer by clicking on your profile picture or initials in the top navigation of Engage. Choose your name from the resulting menu to open your profile details and select the API Keys tab. All keys assigned to you will be listed here, including the degree of access in each key.