Forthcoming Update to Canvas API Response Header Capitalization

[IsaacMoore]

Hello, community,

In a forthcoming update, currently slated to be released as part of the June 19th, 2024 Canvas deployment, all HTTP responses from Canvas – for API users, browser users, and others – will transition to full lowercase response header names. We are making this change to comply with industry best practices. The HTTP Semantics standard (RFC 9110) states that “field names are case-insensitive,” meaning that clients should not rely on header names matching any particular case – and in fact, many HTTP client libraries explicitly normalize header name capitalization to prevent this.

However, while case-insensitive header names have been the standard for many years, some clients still rely on a particular capitalization when parsing responses – including some internal tools at Instructure! Clients and partners should double-check any custom tools, firewalls, or other relevant software that may rely on header names matching a particular case. Of particular importance, if you maintain a tool that consumes the Canvas API, is the Link response header.

What is the Link header? Why do I care?

The Link header is an HTTP standard header that can be used for many purposes – for browser clients, mainly to speed up page load. However, Canvas also uses it to communicate pagination information in API responses; clients can check for links in this header to identify and retrieve additional pages. Therefore, clients that use this field in their pagination logic should verify that they are consuming the header in a case-insensitive manner, or their tool may stop working as intended.

How do I validate my change?

We have already released the change to lowercase all response header names to the Beta environment. This provides an extended period for testing integrations before the change is released to Production globally. If your tool functions as expected in Beta, you may safely assume it does not improperly rely on header name capitalization.

Thank you for understanding as we make this change to align with industry best practices and keep Canvas the world’s best LMS.

[zqian1]

@IsaacMoore I found on Canvas beta, the API response header attribute names are still capitalized. Any suggestions?

Canvas beta API response header attributes

[IsaacMoore]

Hi @zqian1 --

I just checked in Beta and see the header names correctly downcased. What tool are you using in your screenshot? It is possible that, like web browser developer consoles, it parses out HTTP standard headers and displays their names with the proper casing, even though the actual response from the API contains lowercase header names.

[zqian1]

@IsaacMoore I was using Chrome Developer Tools for that screenshot. So maybe Chrome did the capitalization trick for response headers.

I tried Firefox Web Developer Tools today. And I can see those param names are indeed all lowercased. However, I found there is no difference in the response header param naming between Canvas Prod vs Canvas Beta instances, both have lower cased param names. Please see the screenshot attached here.

Any suggestions? Thanks!

[IsaacMoore]

Hi @zqian1 -- the other thing to note is that if you use an http/2 connection, header names are required to be lowercase, per the standard; so our infrastructure automatically lowercases header names for http/2 connections. If you can force http/1.1 (either in Firefox or with a tool such as curl), you should be able to observe the capitalized headers in production.

[DaneMiller]

What is the time / time-range on the 19th that this update will be applied?

[IsaacMoore]

Hi @DaneMiller -- this change will be deployed in the morning on Thursday, June 20th, due to the Juneteenth holiday on the 19th (Wednesday).

[swaldie]

Hi Isaac,

Who can I contact to determine when this was implemented at my site?

I'm seeing other indicators that it was back in April.

[IsaacMoore]

Hi @swaldie -- this change is not active for any customers. It was briefly enabled for some customers yesterday but later reverted, due to an unrelated issue we encountered. We plan on fully releasing it later today, or this coming Monday.

Before yesterday, this change had never been enabled for any customers in the production environment.

[swaldie]

Thank you, Isaac.

The GET response indicates that http/2 is in use for us:

And up until last month, we've always been able to find the pagination info by searching for "Link: " (capitalized), as that is what was returned.

Though we can see now that is no longer the case.

[IsaacMoore]

Hi @swaldie -- the http/2 spec requires that all header names be lowercase; and therefore, our load balancer has been transforming header names to lowercase for http/2 connections as long as we've supported them. This blog post (and the change that will be deployed soon) is only applicable to http/1.1 connections.

Might it be possible that you previously were connecting with http/1.1 (where you will see capitalized header names, until this change is applied), but are now connecting with http/2 (where they have always been normalized to lowercase)?

[swaldie]

That I'm not sure.  Here's an example of a command that is used, which doesn't include anything specifying the version.

And that hasn't changed in the 3 years since the program executing it was deployed.

[NickChevalierUT]

Hi @IsaacMoore - has this change been deployed to production yet? I have an app that uses the Link header (currently capitalized) to recursively run the Page Views API. I used the app in production earlier this week (and again just now, upon first seeing this blog), and everything is working just fine still using "Link" capitalized.

If the change has already been deployed to production and my app still works, I won't touch anything! 🙂

Thanks!

[Fergus-Wood]

We are now seeing lowercase "link" on production Canvas API responses.

FYI - the API documentation still references the uppercase Link.

https://canvas.instructure.com/doc/api/file.pagination.html