designing better uris

I was looking over the our team’s coding style guide recently when I came across an article on W3.org about designing URIs for longevity. It appears that Sir Tim Berners-Lee wrote the article in 1998, however, I found it at an opportune time.¹

What makes a cool URI?

A cool URI is one which does not change.

What sorts of URI change?

URIs don’t change: people change them.

— Tim Berners-Lee, “Cool URIs don’t change”

I’ve been working on a number of changes to the organization of my website of late. While none of them necessitated a change in the URIs for my posts, I wanted to change the default from a /blog/yyyy-mm-dd/title to a flatter, simpler, /title. This change is part of a larger shift in my thinking about how these notes work from a chronological record of what I’m learning to an encyclopedia that I can visit to refresh myself on topics I’ve found interesting in the past. While each entry is written at a point in time, as Sir Berners-Lee points out, documentation can change with versions. As I learn more, I want the incentive to update the document rather than create a new one. Getting rid of dates helps with that.

So, why is all of this relevant to Sir Berner’s Lee point that “Cool URIs don’t change”? Because what I was proposing would break all of my URIs. Even my small corner of the internet would be affected, because while I could control how all of the internal links worked, I’d shared links with the wide world. Google had crawled my site.

One of the guiding principles for TC39 and the evolution of Javascript is to not break the web. I love that. I want to live up to that standard too. So, what did I do? I continued on with my redesign, but I also created redirects for each of the old links.

https://stephencharlesweiss.com/blog/2020-05-29/aws-cli-authenticate/ redirects using Gatsby’s createRedirect action to `https://stephencharlesweiss.com/aws-cli-authenticate/

While this creates an extra layer of complexity and contributes to my site build times (I now have to continue to build the old page and create the redirect), at least the links to my site still work.

More importantly, it’s a good lesson for how poorly designed URIs can create work down the line. Measure twice, cut once.

Footnotes

• ¹ I say appears as one of the points made in the article is that authorship can change, however there’s a “(c)1998 [Tim BL](https://www.w3.org/People/Berners-Lee/” at the bottom of the post.