Upcoming changes to enforce pagination for Statuspage's authenticated REST API

[#1]

Statuspage is making important performance-based changes to the authenticated REST API by enforcing pagination for a specific set of endpoints. If you have an existing integration with our REST API, you may need to make changes to your REST API calls to accommodate these changes, so please read on to understand the details.

Which endpoints are affected?

• /pages/{page_id}/page_access_users

• /pages/{page_id}/page_access_users/{page_access_user_id}/components

• /pages/{page_id}/page_access_users/{page_access_user_id}/metrics

• /pages/{page_id}/page_access_groups

• /pages/{page_id}/page_access_groups/{page_access_group_id}/components

• /pages/{page_id}/subscribers

• /pages/{page_id}/subscribers/unsubscribed

• /pages/{page_id}/incidents/{incident_id}/subscribers

• /pages/{page_id}/components

• /pages/{page_id}/component-groups

• /pages/{page_id}/metrics

• /pages/{page_id}/metrics_providers/{metrics_provider_id}/metrics

• /organizations/{organization_id}/users

What's changing?

As of Aug 31, 2022, all GET requests made to the above endpoints accept the following pagination parameters, which are both initially optional:

• page - Page offset to fetch

• per_page - Number of results to return per page (note: for backward compatibility, /pages/{page_id}/subscribers will continue to use the limit query parameter)

These parameters will instruct the REST API to return a paginated set of results for a given endpoint, specifically returning up to per_page results that are offset by page. Previously, all GET requests to the above endpoints would have returned the full set of results without being paginated or truncated. Example request and response bodies for each endpoint can be viewed by referencing our API documentation.

As of Feb. 28, 2023, all GET requests made to the above endpoints will have default values unless explicitly specified:

• page - 1st page

• per_page - 100 results

Requests that omit these parameters will return a truncated set equivalent of ?page=1&per_page=100 instead of the full set of results.

What you need to do:

If you’re using any of the endpoints listed above in your integration, please implement pagination for your GET requests before Feb. 28, 2023.

If you have questions about these changes, please feel free to post a comment here.

[Acaboom Suppoprt]

Can I please confirm that the /pages/{page-id}/incidents endpoint remains unchanged and without paging still?
I'm only asking because I saw /pages/{page_id}/incidents/{incident_id}/subscribers in the list of affected endpoints :)

[Vincent Cheng]

Hi @Acaboom Suppoprt, we left out /pages/{page-id}/incidents in the announcement because it is in fact already paginated, with a max limit of 100, so there's no change in API behaviour for that particular endpoint. Hope that helps, thanks!

[Gonchik Tsymzhitov]

Hi @Vincent Cheng , 

thanks for the improvements! :)

[Patrick Heidel]

Hi there @Vincent Cheng ,

I got notified, too through the changes within the statuspage REST API and wanted to have a look through the documentation to get further information how to build up an API the "new" ways. 

Unfortunately there is just an infinity loading screen on https://developer.statuspage.io/ as you see on the attached screenshot. Could you please fix this?


Best regards
Patrick

[Vincent Cheng]

Hi @Patrick Heidel , unfortunately I'm not able to reproduce what you're seeing. Would you be able to verify that you have Javascript enabled in your browser? Could you share what browser/OS you're seeing this with? Thank you!

[Patrick Heidel]

Hi @Vincent Cheng 
thanks a lot for that fast response. 

I am using chrome in the build version 106.0.5249.119 and yes i madesure that js is enabled there. 

Greetings
Patrick

[Vincent Cheng]

@Patrick Heidel Please reach out to our support team via https://support.atlassian.com/contact for personalized support. I suspect we'll want a HAR/network dump next and our support folks will likely have other troubleshooting tips to suggest, but we'll be able to help you more effectively 1-on-1 via support.atlassian.com than in a comment thread here in Community.

[Donovan]

What is returned or what is the response code we receive back if we request a page that doesn't exist. For instance if there are exactly 100 records on page=1&per_page=100 and we request page 2?

Will you return an empty array back to our clients? or an http status code - not found / 404?

I'm guessing we will receive an empty array. I just want to confirm.

I'm particularly interested in /pages/{page-id}/incidents - which as mentioned isn't affected by the API change - but I think the question is still relevant.

[Vincent Cheng]

Hi @Donovan, in that scenario you would simply get back an empty array as a response. Hope that helps!

[Developers at WonderProxy]

Could you confirm that on February 28, 2023, the endpoints listed will also have a maximum `per_page` value of 100?

[Vincent Cheng]

@Developers at WonderProxy Yes, once pagination is enforced on/after Feb. 28, the default and max value for `per_page` will be 100, i.e. paginated results will be limited to 100 results per request.

[Maninder.Kaur]

I'm getting all subscribers even if I specify page offset like /pages/{page_id}/subscribers/?page=4 . However, same query works with 'limit' parameter as it is supposed to be but not for 'page' .  Wondering how can I fetch subscribers based on page offset instead of fetching all ? 

Trying to test before Feb 28th so I can modify my onboarding code accordingly.

[Vincent Cheng]

@Maninder.Kaur The List Subscribers endpoint is unique because it was already paginated prior to this announcement, however this endpoint uses `limit` instead of `per_page` to specify the offset like you've pointed out. In an effort to avoid needlessly breaking compatibility with clients that already use pagination for the List Subscribers endpoint, we've opted to not change that.

Our API documentation contains the full list of accepted parameters for this endpoint (and all other endpoints) and is up-to-date with all upcoming pagination changes: https://developer.statuspage.io/#operation/getPagesPageIdSubscribers

[Maninder.Kaur]

Ahh gotcha, that make sense. Thanks for the quick response!

Btw, API documentation does list 'page' as one of the accepted parameters for List Subscribers endpoint which is what I was testing:) . It doesn't clearly say that this endpoint only uses 'limit' parameter to specify the offset.

[Vincent Cheng]

Sorry, I think I listed the wrong parameter in my last message for specifying the offset (meant to say we use `page`, not `per_page`, to specify the offset for the List Subscribers endpoint). To be clear, the List Subscribers endpoint accepts a `page` parameter for specifying an offset, and a `limit` parameter for specifying the number of results to return; `limit` is equivalent to the `per_page` parameter in use for all the other endpoints that are being paginated as part of this announcement. Both `page` and `limit` are necessary to paginate results with non-default values for offset+number of results from the List Subscribers endpoint. The API documentation is correct here.

Apologies for the confusion; I hope that helps!

[Maninder.Kaur]

No worries and thanks for clarifying, this was indeed my initial understanding except the fact that its mandatory to pass both 'page' & 'limit' parameter to paginate the results. That must be the reason for my query not returning desired results when ran  with 'page' parameter only. I thought as long as page is specified, it will automatically return default 'no. of results' i.e. 100 in this case.  I think it might work this way after Feb 28th.

[Vincent Cheng]

That's correct, with no `limit` specified, currently the List Subscribers endpoint is unpaginated and returns all results. `limit` will have a default value of 100 only after Feb 28, when pagination is scheduled to be fully enforced.

[Maninder.Kaur]

Cool, thank you very much for your help today!

[Justin_Liu]

@Vincent Cheng  Without the total record count information, how do I use the pagination to query all the records. So my question is how to get the total record count at first.

For example: the endpoint " pages page_id page_access_users"

page=????

per page=100

The response does not seem to return the total count yet.

Thanks.

[Vincent Cheng]

@Justin_Liu As long as there are further sets of paginated data available, the API response will contain a `Link` response header with a URL that points to the next set. The absence of this response header indicates that there are no further records to fetch. We do not make available in the API response the total record count, sorry!