API – An Introduction
Almost every organization uses a host of applications to make life easier and business more efficient – Accounting & Payroll Software, Customer Relationship Management Systems, email, instant messaging, Learning Management, Access & Security systems, etc. This list can go on and on.
Too often, these systems operate independently. They were purchased from and developed by different providers using various technologies, each with their own architecture and data structure. Is this bad? No. I need my Accounting Software and my Learning Management System to perform jobs and both require different data to complete those jobs successfully. But what about the common elements? As an employee, I have a record in both the Payroll system and the Learning Management system. But if they don’t speak to each other, how do they stay in sync?
Expanding this thought, if Salesforce records that I purchased a tool, wouldn’t it be nice if it shared that insight with my LMS so that I am offered training on that new purchase? These and other integrations can be performed using APIs. Let’s explore how.
What is an API?
First, APIs and IPAs are not the same thing. API stands for Application Programming Interface. Yes, I understand this acronym sounds scarier than India Pale Ale but bear with me. The concept is easier than it sounds. Applications have inputs and outputs – data the application receives, stores or processes, and data they output. An API provides the interface for one application to request information from another application and/or send data to another application. Essentially, the API is a middle-man helping facilitate the passing of this data… but how?
Run a quick search on “what is an API?” and you’ll see lots of analogies. A common, simple example is that of a restaurant menu. When I go to a restaurant as a customer, I don’t know all the ingredients in the kitchen. I don’t know their recipes and, furthermore, it is unlikely that they are going to let me go poke around the larder. So, how do I get the output I want? Through an “API” called the menu.
All I need to do is order the #4 (placing the API call) and receive back a dish formatted in a specific way. I don’t need to know how the recipe (or data) is assembled by the restaurant (or application). I just need a consistent way to request and receive it. Similarly, as an application making a request for data through an API, I just need to know how to make the order. I don’t need to sort out how the other application gathers that information I requested.
Can I substitute salad for soup? Maybe – some APIs allow you to add parameters to the call to modify the output, while others take the “blue plate special” approach where no substitutions are allowed. One thing is for sure, you can’t take a menu from one restaurant to another and expect the new restaurant to understand the order. Menus are unique to the restaurant, just like APIs are unique to an application.
For the purpose of this blog, we won’t drill down too much further into the technical weeds around APIs and different types (REST, SOAP, etc.) For more information, API University has a good series of articles on the evolution of APIs.
So, how do I use an API?
The reality is, you likely already use APIs without knowing it. When you post a picture to Instagram and allow it to also post in Twitter, you are using an API. Has a web page ever asked if it could track your location? If you clicked yes, then you just used an API.The big benefit of APIs is that they make end users’ lives easier by letting different applications share common data. Click To Tweet The big benefit of APIs is that they make end users’ lives easier by letting different applications share common data. Application developers build the API calls into their applications when that data is needed – like your GPS coordinates for sorting a map or exchange rates to convert currency in real time. You and I just carry on, thankful that we know how long the drive time is to our next meeting. But how do the developers know what APIs are available?
Most applications provide a library of base APIs that developers of other applications can use to fetch or update data. The API Documentation is very specific as to the way the call is placed and how the data must be structured. Let’s look at an example.
In the RISC API definition below, there is a short description – create a new profile or student record in the VTA Learning Management Suite. To do so, the definition provides the fields that can be sent to populate the record noting what is required, what is optional and the format for the data to be included in the call (the parameters). Because the calling application will want to know if their update was successful, return values are defined. In this case, those concerns are success or error messages. Finally, some notes are included around configuration.
Create Profile (Basic)
|Description||Creates a new profile record in VTA|
· ProfileID (VTA)
· ProfilePrimaryKey (VTA)
· ProfileID (VTA)
|Notes||Only one of DeptKey or AlternateDeptID should be set.
 Set to “auto” for automatic generation
Use Case: Salesforce Integration with RISC VTA
To see this API in action, let’s consider the case where a new contact or account was created in Salesforce. As a result we want the same user created in RISC’s VTA LMS. This short video shows how the Salesforce application can call the RISC API for creating a profile in order to add a new user to the LMS.
Pretty cool, right? Now what if we want to go the other direction? For example, we update a student record in the LMS and want Salesforce updated so the records match. No worries, Salesforce has a list of APIs that the RISC VTA LMS can call to do just that.
In the example above, RISC’s VTA LMS is calling a Salesforce API to update a student record when changes are saved in VTA.
So, what is the potential? What all can we do?
When using APIs for system integration, it’s important to consider which application will call the API. That is, who is initiating the program to run? Some of the generic RISC VTA APIs include:
- Find Profile – A third-party application will call this API providing data like an email ID, employee number of logon ID and have VTA Return almost all of the information associated with an employee such as their name, site, job title, email address and even custom fields.
- Create Profile – As discussed above, this API is called by a third-party system sending student information to create a new Student profile within VTA.
- Update Profile – Similar to the Create Profile above, a third-party application will call the Update Profile API to update a student’s site code, name, ID and Password, email address and other student fields. This is also the API that can be called to mark an existing profile as active or inactive. For example, a CRM might call this profile to inactivate students in the LMS when a contact (or company) is made inactive in the CRM.
- Find Course – The Find Course API is called and passed a parameter to receive in return the primary key of the course, along with its title, status and whether the course is self-study.
- Get Course Schedule – Would you like to display courses scheduled in VTA in another application? The application can call the Get Course Schedule API to receive back the Course, Start and End Dates, Roster Counts and Cancellation days.
- Check Prerequisites – If you are going to enroll a user into a class in VTA from a 3rd party system (using an API), the Check Prerequisite API is called in advance by the other system to check a student’s compliance with the class prerequisites.
- Find Self-Study Student – The Find Self-Study API locates an employee enrolled in a self-study course. Details about the registration are returned.
- Register Self-Study Student – Calling this API allows the calling application to register a student into a self-study course so that it shows on their in-progress training. That means, when an employee logs into a new application for the first time, that application can call the LMS and register the student in a course on how to use the application – no administrator action required.
- Register Instructor-Led Student – Similar to the API above, the Register Instructor-Led Student API allows a third-party application to register a student into a specific instance of an Instructor-Led course in VTA.
- Give Student(s) Credit for Course – Is it possible that performing some task using an application or software package might serve as “credit” for completing a course in VTA? The Give Students Credit API can be called by a third party application, passed a course, student and completion data to have the API create a history record for that student.
- Create Order – Do you have an existing e-commerce tool for selling products or services? This tool could call the VTA Create Order API to ‘share’ a course purchase with RISC’s Learn4ia system. Once the order is created, the purchaser can move directly into Learn4ia Order Management to assign out the purchased classes.
- Find Department – The Find Department API allows an application to request information on a department such as the department name, site, and supervisor’s including email address and security role.
- Create & Update Department – Is there a system that already manages your organization structure and the assignment of supervisors? Why not let that system call the RISC API for Create or Update Department to keep them in sync. There are also APIs to add, update and remove Supervisors from Departments to further automate the keeping of evergreen data.
- Get Course Completions (for Department) – Would it be nice to show class completion dates in your Performance Management system? Just have the Performance Management System call one of the RISC Get Course Completion APIs to get completion dates for students.
- Schedule ILT Course – Want to schedule sessions of a training event from another system? That system can call the RISC API for creating scheduled sessions to add the sessions to VTA without logging in.
There are lots of existing, stand-alone, and generic APIs for RISC’s VTA Suite as well as bespoke APIs based on system needs. If you are interested in integrating third-party applications with VTA, contact firstname.lastname@example.org to schedule a time to discuss or request additional API documentation.