Overview
Restful API v1.5 is a significant upgrade from v1. 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 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:
- The User Experience, modules, services, and underlying data models have changed in response to new clients and new ways of learning
- Technologies and industry standards have changed in response to new threats and opportunities
- Absorb has seen a huge upsurge in LMS usage, placing an ever-increasing burden on existing infrastructure servicing API requests
- 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:
- A service gateway now manages and satisfies all API requests
- New architecture to handle immediate and planned changes
Non-optional pagination support for 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 improve security and remove service interruptions and processing bottlenecks is to upgrade all users to Version 1.5.
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, 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 in their production environments.
To enable it on your sandbox, your dedicated CSM or Account Manager can request an access key be generated. The new key must be used to access v1 on the sandbox as well, so please choose a time when there is no ongoing v1 sandbox testing. If you have hard-coded the previous v1 access key, these references must be updated to use the newly generated key.
Will there be a service interruption during the upgrade process?
On production portals, v1 and v1.5 are different products, so you control when and how the switch to v1.5 takes place. The two API versions can even be run in parallel or on different production portals if a phased upgrade approach is desired. The only interruption in production environments will be on March 31, 2023, and that one will be permanent.
To enable it on your sandbox, your dedicated CSM or Account Manager can request an access key be generated. The new key must also be used to access v1 on the sandbox, so please choose a time when there is no ongoing v1 sandbox testing. If you have hard-coded the previous v1 access key, these references must be updated to use the newly generated key.
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.
Until June 30, 2022, Absorb has engaged a group of early adopter clients first to 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, which 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 meets 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 on March 31, 2023, so all clients need to be upgraded to v1.5 by then.
What happens if I don’t upgrade?
After March 31, 2023, 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 is 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 leveling, 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 20 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:
- a) Represent open-ended GET calls that tend to return large data sets
- b) are called frequently
The 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 the information you need in the format you need.
- 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. Filtering is one of the most useful features that will allow more precise queries. The primary use case will be to find the relevant records based on a search of a particular category.
Filtering is available on most parameters, but not all. Further details are available in the attached technical documentation.
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=20”. 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