I'm building a music theory API. I typed F# as root note into the "tonic" interface, which OpenAPI translated into a URL and I got a subsequent 404. Everything broke. Here's what happened and how I created a work-around.

What # means to a URL

The # character is reserved in URLs to signal a fragment identifier. Everything after the # character is interpreted by the browser as an anchor on the page, not part of the path. So something like /scales/F#/major is parsed as /scales/F with fragment major. The server never even sees the # and we get a 404 error response right away when trying to render in OpenAPI.

What the # symbol means to a musician

The sharp symbol in music applies to a note name to raise it by a semitone. In the context of naming scales, as for the API, the root note is the name given to the scale and so F# must be the root note for a scale beginning on the note F-sharp. This becomes a matching issue in pre-programmed interfaces like OpenAPI interfaces, which weren't designed for music first formats initially but the two now have to "talk to" each other.

The Solutions People have Reached for

URL encoding (F%23), query parameters, string substitution (Fs) are all potential solutions to the issue. Each one works technically, but breaks something musically or semantically, because it's clumsy to annotate to non-technical users, and string substitution like Fs doesn't make sense musically.

The German Naming Solution

German music notation uses the suffix "is" for sharps and "es" for flats i.e. Fis, Cis, Es, but notably B for Bb. Despite the workaround, no special characters are needed. Clean URLs. (Also, it's not a hack; it's a centuries-old naming convention used in some of the greatest musical traditions.)