Your API sucks : standards

Standards are great. They help users understand what to do, they allow developers to write libraries that support multiple packages. Use them when you get the chance.

Not invented here

Sometimes companies can’t help themselves. They need to use something they control, to lock developers in, or because they’re agrophobic, or just to be different. It’s very annoying.

If you really want to ruin a developer’s year, however, take a standard, and almost implement it. Ask anyone using CSS or JavaScript in IE6. Or Netscape Navigator. Ask anyone who uses K&R braces in C# code. Or ask these guys:

At one time I had the pleasure of using WorldPay’s api. It was XML based but instead of just saying ‘it uses XML’ they spent a lot of the documentation describing what they meant by XML, e.g. “an attribute value is enclosed in double quotes”, or “the ‘>’ character must be escaped with >”. This always left me worried that they had written their own parser that might reject valid XML if it didn’t match the subset they described in the documents and if whatever library I happened to be using decided to put an attribute in single quotes or use a CDATA section to avoid escaping content it might go horribly wrong. – Comment from Duncan Booth

Use the platform

Once you have a standard, stick to it. Don’t mix your styles, don’t invent new ways of doing things. Users should only have to deal with one library at a time, not mix-and-match like Frankenstein’s monster.

{
    Name : "Your Woman"
    Address : "<Line1>My House</Line1>
            <Line2>My Street</Line2>
            <Town>White Town</Town>
            <Postcode>EE11EE</Postcode>"
}
Advertisements

2 thoughts on “Your API sucks : standards

  1. This I agree with almost completely. In 99.9999% of the cases usage of an existing standard is likely to be the better choice and in the majority of those finding a library (even if there is a $$$ cost) is likely to be the road that leads to maximum ROI.

    Yet, that still leaves the choice of which standard and then which implementation and 1ppm of cases (and with the number of efforts this does actually add up) there can be a compelling reason to “go custom”.

    As always, I recommend doing a proper analysis (it does not need to be long or involved in the vast majority of cases) rather than ever accepting something as a universal “best practice”.

    Liked by 1 person

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s