sendgrid / docs

Repository of Twilio SendGrid's product documentation.
https://sendgrid.com/docs
MIT License
235 stars 967 forks source link

Undocumented "Link" response header #6413

Closed Jericho closed 3 years ago

Jericho commented 3 years ago

@kevinchalet and @jsgoupil recently brought to my attention that some endpoints in the SendGrid API return pagination information in a response header called Link. One example of such an endpoint is suppressions/unsubscribes which is the endpoint to retrieve all global suppressions. If you send a GET request to this endpoint, the response includes a Link header which contains information similar to this:

Link: 
    <https://api.sendgrid.com/v3/suppression/unsubscribes?limit=50&offset=50>; rel="next"; title="2",
    <https://api.sendgrid.com/v3/suppression/unsubscribes?limit=50&offset=0>; rel="prev"; title="1",
    <https://api.sendgrid.com/v3/suppression/unsubscribes?limit=50&offset=400>; rel="last"; title="9",
    <https://api.sendgrid.com/v3/suppression/unsubscribes?limit=50&offset=0>; rel="first"; title="1"

However, we noticed that this is not documented: https://sendgrid.api-docs.io/v3.0/suppressions-global-suppressions/retrieve-all-global-suppressions

I did a little bit more investigation and I found a few more endpoints that seem to also include this pagination information (this is probably not an exhaustive list, this is just what I found so far):

Questions

  1. Would it be possible to confirm if we can rely on this header for pagination information?
  2. Can you confirm which endpoints return this pagination information?
  3. We suspect the content of the header conforms to section 19.6.2.4 of RFC 2068 but can you please confirm?
  4. Will the documentation be updated to reflect this pagination information?