1. Absorb LMS Support & Training
  2. Absorb Products & Resources
  3. Integrations
  4. Restful API

Getting Started with the Absorb RESTful API

Getting Started with the Absorb Restful API

The Absorb RESTful API has been designed to allow customized interactions with your LMS data, including learners, courses, departments, grades, etc. You can also use it to build specialized interfaces, unique reports, integrations, and so on. The use of the API will require technical web experience on your part, but this guide should serve as a jumping-off point for those interested.

Restful API v1.5 is a significant upgrade from v1, which is being sunset on March 31, 2023. We recommend that all clients onboard directly to the new version described below. RESTful API v1 clients must upgrade to take advantage of new features and capabilities.

Frequently Asked Questions (FAQ)

  • Is there a limit to the number of users I can set up with API access? No, you can set up as many users as you wish. We recommend creating a user for each unique workflow that is in place.
  • Does Absorb provide webhooks? Unfortunately, webhooks are not currently available with RESTful API.
  • Is there pagination or limits for API calls? Some endpoints support pagination using the “_limit” and “_offset” parameters. The limit parameter determines how many records will be returned, and the offset parameter determines the page of results (starting with 0) to return. For endpoints that don't support pagination, a useful alternative is to use the ModifiedSince parameter, which is available for most of the larger API calls, to effectively paginate the data (i.e., first return all records modified since 2019-01-01, then 2020-01-01, etc.)
  • Can I request a token or carry out API calls from another domain that's not Absorb? This is known as Cross Origin Resource Sharing (CORS). Absorb's RESTful API does not support CORS. What date formats are supported by Absorb's API? Any date fields will accept a 'plain' date in the yyyy-MM-dd format, e.g. "2021-01-21" or optionally yyyy-MM-ddTHH:mm:ss.fff, e.g. "2021-01-21T18:25:13.000".
  • Does Absorb have an API call limit? Yes, however, AbsAbsorb hast limits which should exceed your typical use case. If you reach the call limit, this could indicate an inefficiency with the how the API is used. In this case, it is advised that you contact your Absorb representative.

What You'll Need to Get Started

RESTful Client

For this guide, we will use the Postman app for Chrome as our RESTful client. This article will cover everything you need to know to use with the Absorb LMS RESTful API, but you can visit Postman - Getting Started if you'd like to learn more about this app. While the workflow in this guide may not be step-by-step the exact same as in your software, the concepts discussed should be universal. 

Your API Private Key

If you are an Absorb LMS RESTful API customer, you will have been provided with an API private key that is tied to your LMS portal. This key is used to authenticate prior to any requests via the API. If you do not yet have a key, please contact us to discuss purchasing one. 

The Service Gateway

All RESTful API endpoints will need to go through the service gateway, meaning you’ll put the service gateway URL before all requests listed in the Swagger document in your portal. Absorb offers region-specific access, and this would align with the region where your portal is hosted.

Your Admin Credentials

Your LMS admin credentials will be used as part of the authentication process. Similar to the admin interface, your admin role will determine which areas of the LMS you are permitted to access through the API. 

Swagger Documentation

Your system admin will be able to access the Swagger documentation by adding “/v1_5-doc" to your portal domain after subscribing to our API service. The Swagger document contains general API information and lists the resources. Each resource has its own URL that defines the API operations on it. Meanwhile, the Swagger document describes a resource, including its API calls and models. There is one file per resource.

Generating an API Token

All requests to the LMS must include an API token as authentication. This token is generated using your API Private Key and your Absorb user account credentials and will be used to verify both client access to the API as well as a specific admin's access to certain LMS data (based on their admin roles set up in the LMS). 

Tokens are only valid for 4 hours after they have been generated or until the same username requests a token, whichever comes first. 

It is important to note that requesting an API token will invalidate any previous token that existed for that user. If you require multiple API workflows we recommend creating one admin user for each workflow to prevent workflows from invalidating each other's tokens. 

To generate a token you'll need to make a POST request to the following request URL:

.../authenticate
  1. Add the service gateway URL of your environment to the beginning of the above string. 
  2. Change your request type to “POST”.
  3. The POST will contain the authentication data in the body of the request. Before you can do this, you'll need to specify a content-type as a header in the request or from the content-type dropdown.
  4. Enter "Content-Type" in the HEADER field and "application/json" in the VALUE field.
  5. You will also need to include the “x-api-key" in the https header by adding “x-api-key" as the key in the header type and the value of it is the private API key.
    Step-5.png
  6. While on the body tab in Postman click on the content-type dropdown and select JSON (application/json).
    Step-6.png
  7. Enter your credentials and privateKey as they are shown below:
    Step-7.png
  8. Click SEND.
  9. Your API token will be returned in the body of the response below:
    Step-9.png

Making a GET Request

GET requests pull data from the LMS and display it in the body of the API response. For example, you could make a request to return a list of all enrollments for a particular user or return information on a particular resource.
In this example, we'll send a GET request to return all the information for a particular user. This request can be made to the following request URL:

.../users/{userId}
  1. Add the service gateway URL of your environment to the beginning of the above string.
  2. Change your request type to GET.
  3. Add your API token as a header to authorize the request. In Postman you can enter this after clicking the HEADERS button in the top-right. Enter "Authorization" in the HEADER field and your API token in the VALUE field. 
    GET-Step-3.png
  4. You will also need to include the “x-api-key" in the https header by adding “x-api-key" as the key in the header type and the value of it is the private API key.
  5. Fill in the Absorb userId for the user you are returning data for. This can be found in the Id column in Absorb's Users report, or alternatively returned via the API in other GET requests.
  6. Click SEND.
  7. A list of learner data will be returned in the body of the response:
    GET-Step-9.png

Making a POST Request

POST requests add new data to the LMS and display a confirmation in the body of the API response. For example, you could add a new department or enroll a user in a course.
In this example, we'll send a POST request to add a new user to our LMS. This request can be made to the following request URL:

.../create-absorb-account
  1. Add the service gateway URL of your environment to the beginning of the above string
  2. Change your request type to POST
  3. Add your API token as a header to authorize the request. In Postman you can enter this after clicking the HEADERS tab just below the address bar. Select "Authorization" in the KEY field and your API token in the VALUE field.
  4. Similar to the authentication, select content-type for the KEY field and the Value to application/json.
  5. You will also need to include the “x-api-key" in the https header by adding “x-api-key" as the key in the header type and the value of it is the private API key.
  6. Please refer to our Swagger documentation for a full list of body parameters that can be sent with this request, but to create a new Absorb user we only need a handful of required parameters. The departmentId can be found in the ID column in Absorb's DEPARTMENTS report, or alternatively returned via the API in other GET requests. The rest of these parameters will be the data you are entering for this user. 
    {
    "departmentId": "613048f5-87c9-442a-915e-edf63cf517b2",
    "firstName": "Sample First Name",
    "lastName": "Sample Last Name",
    "username": "Sample.user",
    "password": "Absorb2022!"
    }
  7. A confirmation will be returned in the body of the response containing the ID of the newly created user, as well as their username. You can verify that this user has been added by checking the USERS report in the admin interface.
    POST-Step7A.png
    POST-Step7B.png

These are some commonly seen HTTP status codes for the API calls

200 OK
This means that the call was successful.

201 Created
This means a post to create a user, course, etc., was successful.

401 Unauthorized
This means that the user has not been authorized, e.g., the token is expired or invalid.

403 Forbidden

This means the user is authorized; however, the user does not have the correct permission to access the requested content in LMS.

422 Unprocessable Entity

The server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions

500 Internal Server Error
This means that there is an error on our end; please contact support if you see this.

How to Use Swagger Documentation for RESTful API

Our Swagger documentation lists every API request we currently have in our system, as well as detailed information on all request and response parameters. This page is divided up based on different areas of functionality. For example, all course related API requests are contained in the Courses section. In each section, you'll find a list of available request URLs as well as a description.

  • You can find the list of the functional areas on the left navigation and each one of them has its own section.
    Swagger-1.png
  • Each functional area has a list of the endpoints underneath it. Select the top-level section in the documentation and you will be presented with all related endpoints.
    Picture11.png
  • Clicking each one of the endpoints directs you to the location of the endpoint in the page. The endpoint path and sample responses will display on the right side of the page
  • The query parameters, header parameters, body schema and attributes needed are shown in the center of the page.

Error Messages

Error messages for Restful API V1 endpoints will include a message so that you know what action is needed to resolve the problem. The following is an example of an error message:

Error-Message.png

 

Articles in this section

Was this article helpful?
5 out of 8 found this helpful