Alphabet Soup for a Monday

I am the webmaster for three genealogical societies, the North Carolina Genealogical Society, the Virginia Genealogical Society, and the North Carolina Chapter of the APG. I also chair the Technology Committee of the NGS.

In each of these realms, I find myself empowered by open source technology, using the LAMP (Linux, Apache, MySQL and PHP) technology stack. This is a powerful suite of free tools that have been developed by volunteers, or in other ways made available for free use. Much of the technology involved in these sites is — as is commonly said, “Free as in ‘Free beer’ and free as in ‘Free speech.'”

A key technology that I’m using is Joomla. This is an open source web content management system designed to provide a dynamic website, changing as content and metadata is changed in the database. It relies on having LAMP underneath it, and builds web pages from the files on the Apache Server and the data in the MySQL database. While you can have page elements cached if they are frequently used, in general the pages are delivered by querying the database when someone comes to a page, then taking the data and some HTML and styling templates, and assembling an HTML page “on the fly.”

I am not the only person who uses Joomla for genealogy society websites. Among others, there is the Dallas Genealogical Society, the New England Chapter of the APG, and the Nebraska State Genealogical Society.

The most recent of the sites that I have put together is for the Virginia Genealogical Society. I launched the VGS beta website this morning. There is still a lot more to do with that site, but the look and feel and the core functions are available.

In mid December, I had updated the method of shipping calculation on both the NCGS site and the VGS site to use the US Postal Service Application Programmer’s Interface (API). This allows both sites to provide pricing based on what the USPS would actually charge to ship, say a book, from one particular location to another. The API takes into consideration the weight of the item, whether it is a letter or a package, the source and destination zip codes, etc., then returns a price that the Joomla site can add handling expenses to, and display to the buyer.

The shareware module to integration the USPS API with Joomla (from Parkbeach Systems) was probably the easiest of modules to set up, though it did require a brief call to the USPS to request the accounts be put on the production server.

This afternoon, a genealogist who was trying to purchase one of the books from the North Carolina Genealogical Society’s website noted that they were unable to make a purchase. I went over to the site and saw the same symptoms. I hadn’t changed anything since our last order for a shipping item (on December 31), but I dutifully spent hours searching the configurations for some anomaly, some toggle I had forgotten to switch.

Eventually, I needed some dinner and came home to have it. After that break, I came back and started Googling again for USPS API and told Google to sort results based on how recent they were. Up popped a tweet about what was happening, from @floodlight:

USPS decided to update their shipping rate API without telling anyone. #FAIL

Genealogy sites, gardening sites, mommy-and-me sites, all kinds of websites rely on this API, and the USPS decided it was high time that they made sure people knew that phrases such as “Priority Mail” were registered trademarks, so they put the code:


after every one of their registered trademarks. Since none of the developers of integrations with the API had accounted for this, or even knew it was about to happen, and since the USPS API sent the registered trademark symbol as a Unicode character instead of as HTML commands for the character (&reg; or &#x00AE; or &#174;) everyone’s USPS integrations filled up with junk and failed, sometimes in creative ways. Our site simply stopped offering a shipping option, though it demanded that users choose one …

By the way, the USPS website still does not mention this issue, though a quick search of the Twitter stream will show you it’s still on people’s minds:!/search/USPS%20API

So, this is how I spent my evening, fretting over a problem that didn’t need to be there in the first place. Folks: Document your APIs, communicate your proposed changes in advance, please.

The good news in all this is that once I realized that the API was to blame, and not some misconfiguration of my own doing, I went to the company that provides the API I’m using with Joomla, and they had already posted an updated version. Both sites are working fine in terms of shipping and the USPS shipping API.

So now, I can rest. Tomorrow I’m starting an Aikido class with my stepson, but perhaps I will get more of an opportunity to work on genealogy in the evening tomorrow, even with that going on, than I did today. We shall see.