In order to access and utilize the web services API, your institution must possess the appropriate product licensing. If you are not sure if your institution has licensed access to the API, please start by contacting a representative from the office, department, or division responsible for purchasing the product. If you are still unsure, contact Engage Support (firstname.lastname@example.org) and we will be happy to put you in touch with the appropriate representative from our team who can assist you further.
Once you have confirmed you have access to utilize the API, you will need the following:
- A web developer or application programmer familiar with the concept of APIs or who is willing to learn
- A web server from which to run the code you or your developer/programmer will write to interact with the API (note: depending on what you intend to do with the data you extract from the API, you may also need a database server)
- The IP address of the server above
- At least one public/private key pair for authenticating your access to the API
A key pair consists of a public key (i.e., a special "username" for connecting to the API), and a private key (i.e., a secret value that will be used as a part of your "password" for connecting to the API). Both of these values will be selected for you and for security purposes they will only be given to you or the appropriately-designated individual over the phone. In order to receive a public/private key pair, your institution must first have been verified as owning the appropriate license to use the API. You can have your assigned campus consultant from Campus Labs request a key pair for you, or you can send a request directly to Engage Support (email@example.com). Requests should include:
- Institution name and Engage URL
- User's name and their Title or Position
- The user's contact email address and a direct office telephone number
- IP address of the server from which you will communicate with our API
- A brief description of the types of data you intend to access through the API
You will also need to tell us the encryption algorithm to be used for authentication. The supported types include:
Workflow of using the API
Once you have been granted access to the API and have been given a key pair, you can start writing your code. Your code will need to do the following things:
- Define the libraries needed for creating hash values, parse XML or JSON data, and perform any other operations, such as database updates.
- Set your request header Content-Type to either text/xml, if you want the API to respond with XML, or application/json, if you want the API to respond with JSON. If you do not specify a Content-Type, you will receive JSON.
- Construct a request string, then make a call to the URL you created above.
- Parse the response from the API, starting with the first page where you will examine the total number of returned pages and items.
- Create an iterative loop to call each subsequent page and parse its contained data as necessary.
If you are ready to begin writing your code, please see the documentation on Security and Authentication.