RESTful API v1.5 Upgrade - FAQs

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 quick reference, this article pulls together some frequently asked 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. Throughout 2022, increased monitoring and API clients have reported processing delays, timeouts, and service interruptions.

After a thorough review, we created a new RESTful API version. The benefits of this are:

  1. A service gateway now manages and satisfies all API requests.
  2. New architecture to handle immediate and planned changes.
  3. Non-optional Pagination support for high-use “open-ended” GET endpoints.
    • For more information about best practices for Pagination, click here.

 

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 clients 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 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, Absorb aims to avoid mandatory upgrades in the near future.

 

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

Immediately after v1.5 is released, it will be enabled and available to v1 clients in their production environments.

To enable it on your sandbox, your dedicated Client Success Manager 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.

 

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. If a phased upgrade approach is desired, the two API versions can even be run in parallel or on different production portals. The only interruption in production environments will be following the Absorb Q3 2023 release, and that one will be permanent.

To enable it on your sandbox, your dedicated Client Success Manager 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.

 

What kind of help will Absorb provide during my upgrade?

Besides Knowledge Base articles and sample code, your dedicated Client Success Manager 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 or how to get one, please ask your Client Success Manager or Account Manager.

 

What happens if I don’t upgrade?

Please know that after October 31st, 2023 Absorb will not block the RESTful API v1 endpoints. However, Absorb will cease to resolve any V1 bugs or issues past the October 31st, 2023 date.

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 on-boarding 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 resources required to GET all the data 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:

  1. Represent open-ended GET calls that tend to return large data sets.
  2. Are called frequently.

The current set of Pagination endpoints are:

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

The following endpoints allow Pagination when called with the x-api-version header 1.5.1:

  • /lessons
  • /courses/[GUID]/certificates
  • /tags
  • /instructor-led-course-sessions/[GUID]/session-schedules/[GUID]/attendance
  • /session-schedules
  • /my-courses, /api/rest/v1_5/my-catalog
  • /curriculums
  • /course-bundles

 

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 an 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”.

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?
1 out of 3 found this helpful

Comments

0 comments

Article is closed for comments.