Overview 

Restful API v1.5 is a significant upgrade from v1, which is being sunset at the end of 2022. While new clients can onboard directly to the new version, v1 clients must upgrade to take advantage of new features and capabilities. For step-by-step upgrade instructions, please refer to the Upgrade Guide [link to new kb article Restful API v1.5 - Upgrade Guide].

For quick reference, this article pulls together some frequently asked questions.

Common Questions 

Why did the API have to change?

Restful API v1 has been around since the beginning of Absorb LMS. Since that time, a few things have happened:

  1. The User Experience, modules, services and underlying data models have changed in response to new clients and new ways of learning
  2. Technologies and industry standards have changed, in response to new threats and opportunities
  3. Absorb has seen a huge upsurge in LMS usage, placing an ever-increasing burden on existing infrastructure servicing API requests
  4. In the past year increased monitoring and API clients have reported processing delays, timeouts and service interruptions

After a thorough review, we created a new Restful API version with:

  1. A service gateway now manages and satisfies all API requests
  2. New architecture to handle immediate and planned changes
  3. API versioning, so the use of future changes will be optional
  4. Non-optional pagination support to high use “open-ended” GET endpoints

Why is the upgrade mandatory?

It was necessary to move all API clients over to v1.5 and sunset v1 because all API clients share the same request servicing infrastructure. The only way to remove all security threats, service interruptions and processing bottlenecks is to upgrade all API clients.

How often will I be asked to change my client code?

This upgrade unfortunately represents a "breaking change" (because it "breaks the API contract" and requires client code changes). While this was absolutely necessary to deliver the required architectural, technological and functional upgrades required to achieve the responsiveness and reliability our clients demand, we understand this is an exceptional event. By making major changes now, and by introducing API versioning, Absorb aims to avoid mandatory upgrades.

Do I have to do something to enable access to v1.5?

Immediately after v1.5 is released, it will be enabled and made available to v1 clients.
There are no additional steps for API clients to perform.

Will there be a service interruption during the upgrade process?

At this time, v1 and v1.5 are different products, so you are in control of when and how the switch to v1.5 takes place. The two versions can even be run in parallel or on different portals if a phased upgrade approach is desired. The only interruption will be on December 31st, 2022, and that one will be permanent.

Why am I only being told about the need to upgrade now?

Although the need to provide a replacement for v1 became clear after a January product review, the form and timing of the upgrade were still TBD.
Up until June 30, 2022, Absorb has engaged a group of early adopter clients to first understand their use cases and pain points, and then to evaluate the upgraded version as it was being developed.
This process resulted in significant learnings, and these have been rolled into both v1.5 and the upgrade process itself, for the benefit of the remaining API clients.

What kind of help will Absorb provide during my upgrade?

Besides Knowledge Base articles and sample code, your dedicated CSM or Account Manager can request a member of the Absorb Product team meet with you to answer your questions.
Additionally, our App Specialists have been trained to provide technical support, but their involvement requires a commercial agreement for accessing their services. To find out if you already have an agreement in place, or how to get one, please ask your CSM or Account Manager.

Is there a deadline for upgrading?

We plan to sunset v1 by the end of 2022, so all clients need to be upgraded to v1.5 by then.

What happens if I don’t upgrade?

After December 31, 2022, calls to the deprecated v1 endpoints will return errors.

What has changed in v1.5 vs v1?

For existing API clients upgrading to v1.5, these new features are available:

  • All API requests will go through a Service Gateway, which was introduced to provide increased security and reliability
  • Support for pagination, sorting and filtering on selected GET endpoints
  • User email address no longer required when updating user attributes
  • The user resource has new endpoints, allowing you to:
    • Update, sort and filter by custom fields 
    • Access last login 
    • Access earned competencies
  • Optionally, clients can utilize Oath2 for security

For new API clients onboarding directly to v1.5, and upgrading clients that decide not to utilize the backward compatibility setting, all the above features are available plus:

  • Swagger generated and maintained API documentation
  • Requests and responses in camel case
  • Where pagination is used, the response includes a wrapper with the number of elements in the collection

Do I have to utilize backward compatibility?

Not at all. Backward compatibility was introduced to make the upgrade as easy as possible.
If additional code changes are made to handle camel case and leverage the pagination wrapper, we can turn the backward compatibility off on your behalf.

 

Why is pagination mandatory?

Pagination is a key part of request load levelling, and its use will greatly increase response time. Additionally, when Pagination is used together with sorting and filtering, the need to use GET all resources is greatly reduced.

What happens if I don’t use pagination?

If no Pagination parameters are used, the default parameters will be assumed. This means only the first page, with a maximum of 1000 records, will be returned from a GET call on an endpoint supporting pagination.

Why wasn't pagination added to all endpoints?

Pagination was only added to endpoints that:

  1. a) represent open-ended GET calls that tend to return large data sets
  2. b) are called frequently

Current set of Pagination endpoints:

/coupons
/courses
/courses/GUID/enrollments
/courses/GUID/lessons/GUID/enrollments
/departments
/groups
/instructorLedCourses
/onlineCourses
/roles
/sessions
/users
/users/GUID/enrollments
/users/GUID/certificates

Will pagination be added to additional endpoints?

Possibly, if client requests and/or usage logs support expanding the set of paginated endpoints.
To avoid a breaking change, additional pagination support would have to be introduced in a new version of the API, the use of which would be optional.

What can I do with the new Sort feature?

Sorting is a completely optional feature available on endpoints where pagination is supported.
Combined with Filtering, Sorting extends API user abilities to find information you need in the format that you need it.

  • Use ‘_sort’ query string parameter on specific GET requests.
  • Supply a comma-separated list of sort keys. The default sort order is ascending.
  • Prefixing '-' before the sort key will return results in descending order.

For example:
https:// https://[path]/[endpoint]?_sort=-relevance&term=abc

 

What can I do with the new Filter feature?

Filtering is a completely optional feature available on endpoints where pagination is supported.
One of the most useful features that will allow more precise queries is Filtering.
The primary use case will be to find the relevant records based on search of a particular category.
Filtering is available on most parameters, but not all. Further details are available in the attached technical document.  

Use ‘_filter’ query string parameter on specific GET requests. Supply a comma-separated list of filter operations to be performed. Supported operations (see Appendix B) include:

  • Operators: eq, ne, gt, ge, it, le, and, or, not, ()
  • Functions: substringof, endswith, startswith, tolower, toupper
For example:
https://[path]/[endpoint]?_filter=startsWith(lastname, ‘leb’) or dataAdded ge datetime‘1999-0306T20:38:07Z’

 

How does Pagination Work?

To use Pagination, supply both ‘offset [numeric value]’ & ‘limit [numeric value]’ parameters on specific GET requests to paginate returned results.
Offset is the current page, with 0 being the first. Increment this value on successive calls until no records are returned.
If no pagination parameters supplied, default pagination settings are “offset=0&limit=1000”.

Note: to access records beyond the first page, the endpoint must be called again with an offset value one increment higher than the last call, until no results are returned.

For example:
https://[path]/[endpoint]?offset=0&limit=100

 

 

 

 

Was this article helpful?
0 out of 0 found this helpful