USPS API is horrible

Garbage Names

On January 2nd, USPS changed shipment option names from things like

First Class Mail International Package

to

First-Class Mail<sup>®</sup> International Package**

This is not a bug. This is what USPS intentionally wants to use going forward.

The solution suggested to fix the apis that break on this is to do something like "strip <sup>®</sup> and the **".

That is to say, that programmers should now put in a data sanitizer because USPS has decided to supply a bunch of garbage tags in their latest API. The recommended solution is to drop the new garbage.

Let me take some time and try to figure out how this could have ever possibly went down:

In December there was a board meeting:

Manager: Our brand name needs to be protected. Are we putting a ^® everywhere that our brand "First-Class Mail" appears?
Programmer: Well, not exactly. Our programmer facing API...
Manager (interrupts): I've heard enough. When should we do this? Now, or after we fire you?
Programmer: B..but, this will break everything!
Manager: Well then, we will find someone that will respect our brand.
Programmer (under her breath): Holy fuck...
Programmer: Alright ... no problem sir. We'll have to send an email out.
Manager: The email has already been sent. We can't send out a second.
Programmer: Again, this will break everything, internatio...
Manager (interrupts): One email only. It's already been sent. People will adapt.
Programmer: Let's at least update our documentation by that week.
Manager: The documentation server are due for a scheduled downtime that week. We can't change this - the policy has been set. (yes, they went down that week)

Really odd requirements

Ordering of things that probably ought to not matter, really do for USPS. For instance, This is correct:

<Length>12</Length>
<Height>8</Height>

This is wrong:

<Height>8</Height>
<Length>12</Length>

You have to do Width, then Length, then Height ... and only in that order. Similarly, you have to do Pounds, then Ounces, then Machinable, then MailType, then GXG, then ValueOfContents (mind the case), then Country, then Container, then Size, ... etc... in this order, and only this order.

And when it says it's optional on the documentation, don't count on it. It's required.

Here's how this may have happened, maybe.


Programmer: Let's use XML for our API.
Manager: What if someone specified Ounces first, then Pounds, instead of Pounds then Ounces?
Programmer: The keys are unique, that ordering will not be a problem.
Manager: What if it was a mistake?
Programmer: XML shouldn't care. The siblings orders should be interchangeable in the case of Key/Value assignment like this.
Manager: There should be only one correct way?
Programmer: We would have to go way out of our way to make this.
Manager: We pay you well, right?
Programmer: Ok Ok, let's at least state this in our documentation.
Manager: What? That there is only one correct way? Isn't this assumed? You are a programmer right? Aren't computers supposed to be this pedantic?
Programmer: Yeah well ...
Manager: We pay you well, don't worry about it.

Horrid Documentation

And why on earth does http://www.usps.com/webtools/htm/Rate-Calculators-v1-2a.htm take sooo damned long to load?

A peak at the source reveals:
<meta name=ProgId content=Word.Document>
<meta name=Generator content="Microsoft Word 11">

Yes. They write there technical APIs in Microsoft Word and then just save them as HTML and post them directly to the site. Genius. At least we can scrape a few things:

<o:Subject>Web Tools API Reference</o:Subject>
<o:Author>john.f.johnson@hp.</o:Author>
...
<o:LastAuthor>Amanda Loser</o:LastAuthor>
...
<o:_AuthorEmail dt:dt="string">Sherry.McNeill@hp.com</o:_AuthorEmail>
<o:_AuthorEmailDisplayName dt:dt="string">McNeill, Sherry</o:_AuthorEmailDisplayName>

My first tone of complaint will be the fact that they don't talk about the changes, although they seem to suggest there has been some. You see stuff like this in there example code:

First-Class Mail Interna<!--127 suppressed-->)

So their example code, isn't actually an example; it's a neutered copy and paste that doesn't actually illustrate a full exchange. It fails to serve its most fundamental purpose; which is to illustratively show what one means.