Writing An API Is Hard, And So Is Documentation

This was found in a 3rd party’s API integration guide I had the pleasure of working with. It’s always nice to see someone roll their own data format instead of using JSON or XML, especially when it’s in a web service. The data format description is topnotch as well.

This request type allows you to retrieve a list of real-time inventory levels. This list will contain a double pipe delimited list of denominations pipe delimited by their associated double pipe delimited amounts. For example, a return value of “10.00||25.00||50.00|100||50||25″ represents the following inventory levels

100 quantity of $10.00 items

50 quantity of $25.00 items

25 quantity of $50.00 items

And if that wasn’t enough, the custom message you could include with your API calls allowed for HTML, but Cr, Lf, and <br/> tags weren’t allowed. Instead you needed to use a single line string and || which they would then replace with <br/> for you.

If you’re writing an API, please don’t do this.