Your API sucks : hidden effects

Your API can be well structured and use the right language on the surface, but it can still be a pig if you get it wrong behind the scenes.

Data bloat

Are you sending 1/2 Gb of data for every roundtrip? XML encoding the entire object graph for a call that can only possibly change 1 field within it? Are you wondering why your network is slow?

Busy waiting

Sometimes data is big. It will take a long time to upload and process. That doesn’t have to be a problem. But don’t make me wait whilst you do it. It’s easy to find asynchronous libraries, or just throw the request in a queue and return. Let the client get on with the next thing.

Idempotence

Idempotence is a posh word for a very simple idea : looking at something shouldn’t change it. Quantum mechanics is hard because that’s not true. Your API is not there to impress Niels Bohr.

In other words, GET over HTTP doesn’t change data. Property getters on a class don’t change data. CQRS queries don’t change data. Don’t change data unless explicitly requested to do so.

Don’t get confused though. This doesn’t mean that each get will return the same result, after all tomorrow’s weather will be different to today, but I should be able to change the weather just by observing it.

Hidden prerequisites

Have you ever visited a shopping site and tried to checkout, only to be denied because you haven’t previously added a credit card to your account?

It’s very annoying having a hidden step that’s not clear. If it’s required, make it required at the point of action (definitely my preferred option), or if you can’t do that, deny access to the point of action until the prerequisites are cleared. And make it very clear why access is denied.