API Rant…
For this week’s API rant, a little story from history. When I was a kid, back when telephones were a thing in the hallway, my friends would phone up and say, “is David there?” My father, who, as the man who controlled the phone would sometimes reply, “yes.” And put the phone down.
As he would explain to anybody who cared, the correct question is, “may I speak to David.”
What does this have to do with APIs you may ask? Well, let me tell you.
A discussion this week with @kin lane revealed an interesting conversational and business problem lurking in the API contracts space. When you speak to an engineering team about APIs you’ll often get a different answer from the one if you ask the business operations team.
So, asking, for example, if an API can do something or if it exists will often yield the answer YES. Especially if the API exists, also, asking, can I do this with your API, will also yield an answer YES!
The API exists, therefore it can be used in the way it is designed.
However, while that is a purely technical response, the real question should be, “may I do this with your API?”
And that answer might be very different.
Looking at a specific API problem, imagine you have a sequence of events that happen one after another to achieve an end goal. Let us consider you have an API that will look something up for you, perhaps a list of files, and another API that initiates sending a copy of that file to somebody else. From a User Perspective, this should be simple, present a list of files and select the one to send.
However, what if the two systems work slightly differently, what if the permissions to get the file list are different from the permissions to send? What then? Is this the days of the command line? (Well, when it comes to APIs themselves, the answer there is yes too, probably!)
Well, then you’re going to either have an app or service that shows you a list of file names and another that sends files. Obviously, this is true because we’ve all hit these problems before and despite the fact the APIs exist to do both things, the way they work is designed so that you can’t.
This is frustrating, it’s frustrating for users and it’s especially frustrating for developers because unless you read through all that stuff you probably clicked ‘accept’(1) on without reading you might find that you completely missed that you can’t do what you think you can.
There should be more clarity on this and, from the perspective of the entire markets a way for everybody to be clear on what can and cannot be done with APIs without having to deep dive through dozens of pages of EULA for the API.
While I’m ranting EULAs for APIs that actually are designed for transparency might be nice… but that’s the subject of another rant.
(1) – a whole other rant but one on a topic that is probably cleared up now as everybody has learned the hard way that building your business on somebody else’s API is a problem. Haven’t they?
Begging the question is an informal fallacy if you want to keep up with my habit of picking esoteric stuff to moan about.
Want to discuss this rant or anything else?
Book some time with our chief ranter, he doesn’t bite!
If you’re new to API monitoring, you can learn about our comprehensive features for testing, monitoring, security and performance and sign up for a free trial account.
