You are here

The Human API

In application development (aka programming) you have this construct called the Application Programming Interface (API). The API is simply a set of rules defining how to interact with the application in the way that gets the desired outcome. For instance, if I'm dealing with a financial application and I want to get the balance on an account the API might say to use the "getBalance" function. It might also say that in order to get the balance it needs an account number, as in "getBalance(111477)". So as a developer I now know how to get the balance and the prerequisites I need before try to get the balance.

API's sometimes also define the type of responses a developer should expect. For instance a successful response from getBalance might be $20.17 or 20.17 or 2017. The only way for the developer to know is for the API to define it. If the developer knows that they are getting $20.17 they know that there's no extra work for them. If they know they are getting 2017 then there's a little more work to add on the decimal and currency symbol. If the API doesn't specify anything then the developer knows there's a lot more work and that they have to be ready for just about anything to come down. In those cases the developer has to test everything that comes through. It's really a lot of work.

Another type of response an API might define is an exception. An exception could be anything from a "#45- you sent me the wrong account number" to "#87 - I didn't hear you." This helps the developer know what to do next. For example, if they get "wrong account number" they know to verify the account number before trying again. If they get "I didn't hear you" they try again. If they get an exception that they don't understand, then they can't do anything with it. It just goes into some general exception bucket. Which is mostly useless and a user of the application sees something like "Sorry, I don't know what happened. Call someone."

API's are great... IF they are well documented AND reasonable. What often happens is that the API's either aren't documented or aren't reasonable or more commonly just aren't understood. In any of these cases the developer creates workarounds, either abusing the documented features, or finding undocumented features and exploiting them. It's not necessarily the developers fault. They are just trying to find the quickest and most efficient route to get what they need out of the application.

Human's aren't much different from programs. We each have our own Human Programming Interface, where we take in requests and give out responses. Some of our HPI is common or shared between other humans. Like using the "howAreYou" function returns a response of either "howAreYou", "Good", "Bad", or "Sorry, I don't know what happened. Call someone."

The real problem is that each human's HPI is slightly different and NO ONE provides documentation. You're unlikely to know that Christine's HPI has a "howAreYou" function which is just like Mike's "howAreYou" function but requires the current date be passed. If the date is the 3rd Monday of September, the response will be "Fuck you!", but any other date and "Great! Thank you!" will be returned.

So what happens is that one human learns of another human's HPI by accident. They test out the common functions like "howAreYou" and "whatMovieDoYouLike" and "whatsForDinner" and gauge the other human's responses and build their own documentation. Sometimes one human will get lucky and the other human tells them which functions to use to get the right response like the "giveFlowers" or "setDinnerDate" or "holdMyHand" functions.

However, most of the time we're just fumbling around in the dark trying things out. And what's worse is that sometimes our functions might sound the same but work in completely different ways. So one person's "goToTheater" might require "popcorn" and "action" while someone else's "goToTheater" might require "dinner", "romance", and "live actors". One returns excitement and the other returns connection. But we don't know until the functions have been called and there's a disconnect that lands us in the "Sorry, I don't know what happened. Call someone." category. Then we have to figure out that my goToTheater is actually goToMovie and her goToTheater is goToDinnerAndAPlay.

Another major challenge is RULES. In an HPI, like an API, there are rules for how and when to use certain functions. There are always reasons for these rules. Like don't call "getBalance" with "*" because it will return everyone's balance all at once and crash the system. HPI's have these rules too, like "don't call 'wakeMeEarly' because it will return 'grumpyAssBitch' and 'deathThreats'." Rules are great if they are understood. Rules are horrible when they aren't understood. When someone understands a rule it's because they understand why the rule was created and what it's there to avoid. When people don't have that fundamental understanding then they look for ways around the rule, they interpret the rule to the letter of the rule, and eventually they circumvent the rule in some way that steps right into what the owner of the rule wanted to avoid.

For instance Angie tells Tom, "Here's the rule, don't buy me flowers! Ever!" He hears the rule, he understands it in principle, but he doesn't have any understanding of WHY. Then the next week he's wanting to be romantic, but knows he can't buy Angie flowers; it's against the rules. So instead he has an edible arrangement sent to her at work. Angie then calls Tom and proceeds to chew him out for his romantic notions. In her mind flowers and other similar gifts connected her to a bad time in her life with a previous romance. Every time a man gave her flowers she went back to that bad place. Tom didn't know, didn't make the connection, or didn't see the rule as fitting his edible arrangement. He sees Angie as slightly crazy and overreacting. Angie see's Tom as inconsiderate, disrespectful and dense for not seeing what was right in front of him.

There are hundreds and thousands of such interactions that happen with people that are just like this. Either one person doesn't know what the right function is, what the response will be, or doesn't understand the purpose of the rules and soon enough you have chaos. You get back to that "Sorry, I don't know what happened. Call someone." or worse, "Fuck you!"

Continued later... Refactoring