★ A simple explanation about the API
What is the API?
The Application Programming Interface (API) can be used to send commands or information to aNewSpring or to retrieve information. This can help you to e.g. manage your resources (like users, courses, subscriptions etc.) in aNewSpring and keep them synchronised (up to date) with your own database.
This article will try to explain how the API works without using too much technical jargon. It's not intended for developers, but for other users of aNewSpring that need to understand what the API can do for them.
Are you a developer? We have more specific technical information about our API available here.
API calls
An API call can be a command or you can retrieve information. Our API supports POST requests and GET requests.
POST requests
You can send commands to the API to automatically perform actions that you would otherwise do manually as an administrator. These kinds of commands are called POST requests and can contain information that needs to be stored in aNewSpring.
In response to a POST, the API will let the external system know if the command was executed successfully or if this failed and why it failed.
Example:
POST /subscribe/{userID}/{courseID}
If the integrations sends this POST to the API of aNewSpring, this means that you tell the API to subscribe the user (with an external ID that should replace userID) to the course (with an external ID that should replace courseID).
The API will then perform this action if the user and course with these external IDs actually exist.
GET requests
You can also use the API to retrieve information from aNewSpring. These are called GET requests.
If the GET fails (e.g. there is no user with the given external ID), the API will let the external system know why the information could not be sent.
Example:
GET /getSubscriptions/{userID}
If the integration sends a GET to the API of aNewSpring, the API will respond with a list of courses that the user (with an external ID that should replace userID) is subscribed to at that moment.
If you want to use the API to get course results, you could consider using Webhooks instead. This can save a lot of API calls, because the information will be pushed to your system as soon as it is available.
If you would use the API for this, your system would have to retrieve all the information for many learners e.g. every day or hour, so the information in your system would not be up to date immediately, but with a delay.
External IDs
Most of the resources that you refer to in the API calls (like courses, users, etc.) need to have an external ID in aNewSpring, because that's how the API can identify on which resources to perform the action or where to retrieve the information from. There is more information about all kinds of external IDs and how to set them up in aNewSpring in this article.
Some API calls don't use existing external IDs but are used to set the external ID.
As an alternative to external IDs, many API calls also support automatically generated UIDs.
There is a technical overview of all possible API calls, an example of their outputs and possible response codes in our API documentation.
What exactly are the possibilities?
The API can be used to manage the resources in aNewSpring. This has been summarised below (per resource). The API is also necessary if you want to use Single Sign-On.
Users
You can retrieve (GET):
- the user details and roles of existing users
- if a user already exists in aNewSpring
You can command (POST):
- to add an external ID to an existing user
- to add a new user
- to update the user details
- to delete a user
- to link authors and/or designers to content libraries (or unlink them)
User groups
You can retrieve (GET):
- if a user group already exists
- if a user already belongs to a group
- the users of a group
You can command (POST):
- to add a new user group
- to update a group: changing the name of an existing group or moving it by changing the parent user group
- to link users to a group
- to unlink users from a group
- to delete a user group
Subenvironments
These options only apply if we have set up your learning environment to use submanagement.
You can command (POST):
- to (un)link events and subenvironments
- to (un)link user groups and subenvironments
- to (un)link templates and subenvironments
- to (un)link users and subenvironments
Subscriptions
You can retrieve (GET):
- if a user is already subscribed to a specific course
- all subscriptions of a specific user
- all results of a specific user
Instead of retrieving results with the API, it might be better to use Webhooks.
You can command (POST):
- to subscribe a user to a course
- to change subscription details (like the start and expiry date)
- to unsubscribe a user from a course
- to register a score for an external activity in a specific course for a specific user
Courses
You can retrieve (GET):
- a list of existing published templates that have an external ID (and are not archived)
- a list of courses for a specific template
- details of a specific course
- a list of learners that is subscribed to a specific course
- a list of learners that are linked to a specific instructor for a specific course
- a list of instructors that are linked to a specific learner for a specific course
You can command (POST):
- to create a new course from a specific template
- to change course settings, including linking instructor and observer groups
- to change the permissions of instructors for a specific course
- to change which instructor is allowed to assess a specific activity
- to (un)link instructors and learners
- to delete a course
- to copy a template
Calendar items
You can retrieve (GET):
- if a calendar item already exists
You can command (POST):
- to add a new calendar item to a specific course
- to update the calendar item
- to delete calendar items
Access codes
You can retrieve (GET):
- if an access code group already exists
- if an access code already exists
You can command (POST):
- to add a new access code group
- to generate new access codes
- to add specific access codes
- to add a specific access code and link it to an existing user
- to delete an access code
- to delete an access code group
Events
You can command (POST):
- to add a new event
- to change details and settings of an existing event
- to (un)link instructor and events
- to link an event to a specific event activity of a specific course
- to unlink events
Profiles
You can retrieve (GET):
- a list of profiles
- the profiles that are linked to a user
You can command (POST):
- to link users to a profile
- to unlink users from a profile