A good first step to learn pretty much anything, is
1. The definition
Of course I read the usual ones before. Wikipedia says:
Oookay. Right. For my purposes here, I would like to change the wording a little bit. I want to write it in a way I can understand. Here it comes:
APIs are interfaces for programs to access other programs, systems or devices. The same way buttons are the interface for humans to use things like smartphones. APIs enable the program to do something. They are not programs themselves, the same way buttons are not the human who uses them, nor the smartphone that has them. They are just the entry ticket to using something.
There we go. I will probably have to come back to this, but this seems pretty logical to me. (Am I a bad coderette if I always need those tangible real-world examples?)
Now that we have established what we are dealing with here:
2. How do APIs work?
Let’s start generically. As we already established, APIs are the interface to working with other programs. So generally speaking, they are a way of communication: Our program asks something from the other system through the API and (hopefully) gets an answer back. Normally this happens in a standard format, as the most common APIs are not language-specific. Coming back to the button-analogy: If the buttons have symbols on them that everyone understands, it doesn’t matter if you normally read Chinese or English. Symbols are fine. But there are also APIs that can only be used with certain languages. Like buttons with kirillic symbols on them. Kinda.
3. How to use APIs?
My nemesis question. I wish there was an easy answer, but so far I didn’t have that impression. Generally, there are 2 things to consider: Your request has to be in the expected format and the response also will be in a pre-specified format. Meaning there are no interpretations on how to ask for the information you want. You have to do it exactly in the way the API documentation specifies. And you also cannot really pick what the answer looks like – you will probably have to get it into the format of your wishes yourself. (Unless you want the one you get, then you’re good.)
Unfortunately, all the rest looks to me like it is not that easy to generalize. What exactly you have to do to get information out of something… I will keep looking. Maybe after a few successful tries (as in: copying code from someone who somehow got it) I can find a pattern.
If anyone who has good resources for learning more about APIs for non-CS-background people should stumble across this for whatever reason, please write me a line!