Here we explain everything about (our) API with some nice examples, how you can use it, and why you should use it.

1. What is API?

API stands for Application Programming Interface. It is the interface that allows software applications to communicate with each other. It basically allows you to request for something, or ask a question, after which the API call performs the action it's supposed to do, after you have provided it with information. In our case this would be asking to add a participant to an Exam, Course, or the Academy which requires specific data about the participant.

Example 1

When you go to Facebook in your browser, a request goes out to Facebook’s remote server. Once your browser receives the response, it interprets the code and displays the page.

To the browser, also known as the client, Facebook’s server is an API. This means that every time you visit a page on the Web, you interact with some remote server’s API.

An API isn’t the same as the remote server — rather it is the part of the server that receives requests and sends responses.

Example 2

Imagine you’re sitting at a table in a restaurant with a menu of choices to order from. The kitchen is the part of the “system” that will prepare your order. What is missing is the critical link to communicate your order to the kitchen and deliver your food back to your table. That’s where the waiter or API comes in. The waiter is the messenger – or API – that takes your request or order and tells the kitchen – the system – what to do. Then the waiter delivers the response back to you; in this case, it is the food.

To summarize, when a company offers an API to their customers, it just means that they’ve built a set of dedicated URLs that return pure data responses — meaning the responses won’t contain the kind of presentational overhead that you would expect in a graphical user interface like a website.

2. What do I use it for?

Developers can use different APIs in different ways to build different things. Facebook is a good example; the site launched its developer platform called F8 in May and now hosts an astonishing 10,900 applications from the infamous Scrabulous to instant messaging and food fight games.

The advantage for the host site is that it gets lots of new, cool features for free, while the developers get to promote their work on a more high profile site and build on somebody else's work. Most of these applications are built by companies with their own website - often smaller businesses with less traffic who benefit from the crossover. Movie review site Flixster, for example, has a popular Facebook application, as does Last.fm and the photo-sharing site Flickr.

3. Which API calls does Easy LMS have?

Easy LMS has five API calls which serve different functions:

Add participant to Exam (invite)
Add participant to Exam without notifying (no invite)
Add participant to Course (invite)
Add participant to Academy (invite)
Add participant to Academy without notifying (no invite)

The API calls for an Exam only work when the access is set to A predefined group of participants, or for a Course which is by invitation only. This is self-explanatory for the Academy. It's also not possible to use any of these calls for the same Exam, Course, or Academy when a participant has already been added to it. This is because the aim of these API calls is to add participants, so if they've been added already, the API call doesn't work.

An API call consists of three things:

The payload (the actual data that is sent)
The endpoint (the address to which the data is sent)
The response (success or error response)

The payload is the information that is sent to an endpoint, meaning that data is required to add a participant to the Exam, Course, or Academy.

The endpoint is a web address which the information is sent to, and the response indicates whether the API call was successful or not.

4. Webhooks

Webhooks can be used in conjunction with API calls to initiate different actions. When a webhook is sent that contains the required payload for a certain API call to work, the API call will do its work and add the participant. The webhooks must be sent from your system to our endpoint. This is something you would have to set up yourself in your system.

Example 1 - Course, Exam, Academy

The following paragraphs are part of a fictional use-case to explain how webhooks and API's can work together. 

An HR manager has created an entry-level Course and Exam for newly hired employees. The HR manager wants the employees to take the Course, but only wants them to gain access to the Exam after completing the Course. Only after passing the Exam does he want the employees to have access to the Academy, which contains intermediate and expert-level Courses and Exams. So, how do they set this up?

To understand how to set this up we have already established that these webhooks and API calls will be sent internally within the Easy LMS system. The process is as follows:

The HR manager has to create a webhook that sends a payload to the Exam API after the employee completes the course. This webhook only has to contain the data needed to trigger the Exam API call. In this case, we use the Add participant to Exam (invite) API call. When this webhook has been sent, the API call will be triggered if there's a success response. The API call adds the participant and sends the Exam invitation automatically. 

The second webhook the HR manager must create is for when the employee passes the Exam successfully to gain access to the Academy. Again, this webhook's payload should only contain the information the Academy API call needs to add the participant and send an invitation. After sending this ''Exam passed'' webhook, the Academy API call will be triggered, after which it adds the participant and sends an invite for the Academy.

To summarize:

Create webhook for Course completion which is sent to the Exam API call.
Create webhook for passing Exam which is sent to the Academy API call.
Employee takes Course and completes it.
Webhook for Course completion is sent to Add participant to Exam (invite) API call endpoint and adds and invites participant to the Exam.
Employee takes Exam and passes.
Webhook for passing Exam is sent to Add participant to Academy (invite) API call endpoint and adds and invites participant to the Academy.



Example 2 - Sending invitations from your own system

A customer wants to use our tool for training his (new) employees. They currently use the A predefined group of participants setting to send invitation emails. However, many employees perceive these invitations as spam, and some of these emails also end up in their spam folders. The customer wants to send these invitations from their own system instead.

The customer first creates a webhook that sends a payload to the Exam API - add participant without notifying. When a new employee is added to your system, the webhook sends the payload to the Exam API which adds the employee. The API call does not send an invitation to this employee. When the API call is successful, response includes login credentials. These login credentials must then be sent to the employee from your own system and mail application.

This also works for existing employees, you just need to create a webhook that sends a payload to the Exam API which triggers the action of adding participants without notifying to the Exam. The login credentials returned in the response of the API call can then be sent from your own system.

Example 3 - Selling Exams

A customer creates Exams in our system and sells them to his own clients from their e-commerce website. He wants to automate this after his clients pay for an Exam.

To automate his sales process he will need to use a webhook. When his clients purchase or pay for an Exam on his e-commerce website, they are added to his system. The webhook he creates must be triggered after they have paid. This webhook will then send the relevant payload to the Exam API call and must return either a(n) success or error response. If it's a successful response, the API call adds and invites his clients to the Exam they paid for.



5. When do we use each of the API calls and what are their specifications?

As each API call has a different function they can be used to achieve different things. For example, Add participant to Exam (invite) can be used to add a participant and send an invitation for an Exam automatically when this trigger is activated.

Our API accepts application/x-www-form-urlencoded or multipart/form-data and json.

Find out more about our Exam and Academy API calls in this article.

Find out more about our Course API call in this article.
Was this article helpful?
Cancel
Thank you!