Changes to the User Extended by Role for Next_Link

Lindsey Bryant

@Stephen Boyle did something change yesterday regarding the “next_link” on the User Extended by Role yesterday? I didn't see anything in the Change Log and we ran into issues due to how our developer was using this link to determine if he needed to run the API again.

If it did change, are there other APIs that were also impacted that we need to adjust?

Jared Harbour

@Lindsey Bryant yes something changed yesterday. we found that the URL we were assigning to the next link was incorrect, and we had to adjust how we set the marker value because of a new parameter we added so the page size can be adjusted.

Moving forward, might I suggest that you use the count value returned along with the pagesize value to determine if the call needs to be made again? For example, if pagesize is set to 500 and the count of records is 349 (less than page_size) then you have reached the end of the line.

No other api calls were effected by the changes made, this change was limited to the user extended API route.

Lindsey Bryant

@Jared Harbour thanks for the update. Is there a reason this wasn't included in the weekly release notes? I'll make sure to pass this along to our developer.

Stephen Boyle

@Lindsey Bryant
That was an oversight. There wasn't a change to the schema, so I didn't notice it and didn't inform our Docs team of the change. But there was a change to the output, so it should have been included - which I am remedying asap.

Jon Gosling

@Stephen Boyle @Jared Harbour - This one had quite a big impact for us in prod since we use it to calculate net change on enrolment. Looks like you dropped “school” from the route definition which was causing 404s. We can reconstruct the uri from our end but that's gonna require an urgent prod deployment. Should we do that or should we hold off for a fix on your end? Let me know your thoughts. Also, off the back of this, I realise that we're struggling to find how we get in touch with your support team in scenarios like this - what should we be doing? Cheers, Jon

Eric Eskildsen

Seconding the impact. This endpoint is critical for us. We use it in account lifecycle management for many schools. Changes can have downstream impacts on their systems, Google Workspace etc. We use this endpoint for almost all our schools in one form or another.

Fortunately we have mechanisms in place that prevented a catastrophe here, but just calling out that knowing any changes to this endpoint is very important to us.

Stephen Boyle

@Jon Gosling @Eric Eskildsen
Fix incoming. There was essentially a buried text replacement that inserted “/school”.

Sorry for the complications this caused.

Stephen Boyle

@Lindsey Bryant
An update on this.
The previous change is being corrected, so there should be no breaking change anymore.
The output for “next_link” will be the same as before and will now observe the new “page_size” parameter when calculating the user ID returned for the "marker" (which is the update we were providing in the first place). My apologies for the complications this caused.

Lindsey Bryant

@Stephen Boyle
Thanks for a heads up.

Lindsey Bryant

@Stephen Boyle, @Jared Harbour

We're finding that the last link is defaulting to 500, even when the last page has less than that.

Current URL https://api.sky.blackbaud.com/school/v1/users/extended?base_role_ids=1&marker=5829210&page_size=500

Count :500

Current URL https://api.sky.blackbaud.com/school/v1/users/extended?base_role_ids=1&marker=5829711&page_size=500

Count :500

Current URL https://api.sky.blackbaud.com/school/v1/users/extended?base_role_ids=1&marker=5830211&page_size=500

Count :299

Current URL https://api.sky.blackbaud.com&page_size=500

Can you double check this?

Stephen Boyle

@Lindsey Bryant
The default is 1000 - if you do not include the page_size parameter.

And regardless of page_size value, the results will return up to the page_size value in records. If the count is less than the page_size, then that is the last page of results.

If you include the page_size parameter in your call, the next_link will include the parameter in it's URL as well. Thus, your calls will continue to return the same size pages with each call. The next_link is simply a convenience field, so you don't have to build the URL with the new marker value each time. You can change the page_size value with each call and it will return that many records, starting at the user ID provided by the marker parameter.