API Basics

If you've never worked with REST API's in the past, hopefully this document can serve as a good springboard for you to start using ours.

API's are not Excel exports If you're used to a process heavily dependent on passing spreadsheets around, you should know that this is not the same thing. API's are for direct (computer-to-computer), automated, and rapid or near-real-time communication. Involving humans in the process breaks it completely.

This process is probably best handled by your school's IT department or your department's IT Team.

Step away from the Excel, and prepare to embrace a brave new world of automated integration!

Getting data from AlumnIQ

Most of the time, you'll be PULLing data from AlumnIQ. There are some places where you can use the API to PUSH updates and new data to us, but to get started we'll only focus on the PULL aspect.

The process goes like this:

1. Your program makes an HTTP request to get some data

2. The AlumnIQ API returns the data as JSON

3. Your program parses the JSON into your language's data format

4. You use the data to update your database

Making an HTTP Request

Most programming/scripting environments have the ability to make HTTP requests:

• Unix/Linux computers can use curl (docs) or wget (docs), among others.

• Windows Powershell users can use Invoke-WebRequest (docs) or Invoke-RestMethod (docs).

• Python scripts can use the requests module (docs).

• Oracle supports UTL_HTTP (docs) though we strongly recommend against embedding API logic in your database scripts. Generally integrations require more logic than is ideal to keep in the DB.

When browsing our API docs or the docs on help.alumniq.com, you may notice that we sometimes use these verbs prominently: GET, POST, PUT, and DELETE. They roughly correspond to READ, CREATE, UPDATE, and DELETE. When making an HTTP request, you will get to provide a verb (or method); with the default usually being GET. You can change that to POST or PUT (where allowed by our API) to push data into AlumnIQ.

Generally, our customers create recurring scheduled jobs to pull data from the AlumnIQ API on a regular basis (e.g. daily), and those jobs manage the process of making the HTTP requests, handling the JSON response data, and updating the databases.

JSON Data

JSON is a web standard for transmitting data efficiently. It can include Objects (sometimes referred to as structs/structures or maps), Arrays (sometimes called lists), numbers, strings, nulls, and booleans. Objects and arrays can contain more objects and arrays, and numbers, strings, nulls, and booleans.

Most modern programming environments have access to some libraries or tooling that make working with JSON easy.