Bookmarking for Enrollments Index API in upcoming release

nardell

This question may be covered in the release notes and missed it. One of the pending changes is the "Bookmarking for Enrollments Index API". It seems that this change will be applied production Canvas instances on June 17.  I believe understand the affect of the change - the Link section in the Response Header will no longer provide a range of pages, as in:

; rel="current",your.institution.instructure.com/api/v1/courses/:course_id/enrollments?page=2&per_page=100>; rel="next",your.institution.instructure.com/api/v1/courses/:course_id/enrollments?page=1&per_page=100>; rel="first",your.institution.instructure.com/api/v1/courses/:course_id/enrollments?page=3&per_page=100>; rel="last"

Instead links will be returned as:

:course_id/enrollments?page=first&per_page=100>; rel="current",your.institution.instructure.com/api/v1/courses/:course_id/enrollments?page=bookmark:WyJTdHVkZW50RW5yb2xsbWVudCIsIkxhc3RuYW1lLCBGaXJzdG5hbWUgIiwxMjM0NTY3XQ==&per_page=100>; rel="next",your.institution.instructure.com/api/v1/courses/:course_id/enrollments?page=first&per_page=100>; rel="first"

..henceforth it will be necessary to recursively follow links in any API code that uses the the Enrollments endpoint. Just want to make sure I have the story correct. It seems since this would be a potentially breaking change for an institution's integrations (if the integration relied upon explicit page numbers in its page-following scheme) and Instructure is providing a period of time for the institution to accommodate this change, which is soon coming to an end. I am curious if anyone knows if Instructure is moving away from providing page ranges in REST responses. Though I do not depend on the page numbers in production code in use,  I appreciated that it allows for parallel execution of API requests. 

Thanks,

Michael Nardell

nardell

There is an interesting question lurking in the background - what promises of immutability are made by the data returned by bookmarked indexes? In the case of the Gradebook History and Grade Change Log APIs (both return bookmarked links) we can expect that the underlying data to remain immutable.  Enrollment data does change and I have verified that a bookmarked URL will return different data when there are changes to class Enrollments. (the bookmark does not name a value but is a reference to a parcel of mutable state).