Basic tech concepts for Software Product Managers explained simply
There are many great articles and explanations on this topic (list at end). I’m adding another since I will try and make it pass the ‘mom test’- explaining it so that an intelligent person without a background in the field will easily understand. The intent is to provide a starting point, and broad strokes.
10,000 foot view — it’s how applications talk to eachother.
What? Isn’t that programming languages? Isn’t that wifi or bluetooth? I once heard of a port isn’t that it? All this is not unrelated, but as a rule of thumb, I propose we start with cake.
You want to look up a recipe for cake online using your mobile phone. You open your RecipeX app and browse cakes by image until you find the one: decadent chocolate mousse. You click on it and are redirected to a detailed view of Decadent Chocolate Mousse. While it’s loading, let’s understand what is happening underneath the hood.
Where is that recipe data coming from? The picture of the cake, the ingredients text, instructional text— where does it ‘live’? It’s not yet on your mobile phone, otherwise we wouldn’t have to wait for it to load, right? Most likely it’s in the ‘cloud’, which means a physical computer on earth probably close to your physical location. That computer knows how to store the recipe information, and it knows how to provide the recipe information whenever someone asks for it. It’s listening, waiting to serve you. So it’s aptly named a ‘server.’
So basically, your RecipeX app asks the app that manages the recipe database — hey, please give me the recipe for Decadent Chocolate Mousse. And the app that sits on the computer in the ‘cloud’ is listening, and — if you ask nicely enough in a particular way — will do what is requested. The way they talk defined via the application programming interface, or API. See, it boils down to how computers talk.
By clicking on the small picture of cake in RecipeX, you are asking for the cake recipe information. That is, you send an ‘API request’ to the app on the server, asking for that specific recipe. Additionally, you specify which recipe you want, via a unique ID.
And now — bam! The app on server receives the request, and knows what to do: look up the Decadent Chocolate Mousse recipe in the database, retrieve it, and serve it back to your recipe app. One doing so, the server sends the information back in a ‘response’ back to your recipe app. Your recipe app can successfully display the detailed cake recipe information of Decadent Chocolate Mousse on your mobile phone. Yum.
The request (give me the chocolate mousee recipe!) that RecipeX app sends looks like this:
GET /recipes/recipeID_123
The application on the server that receives the GET request is programmed to be able to receive that type of GET request in that particular way. After retrieving the information from the database, it sends it back to RecipeX via a ‘response.’ The response contains the information stored for the entry with the ID requested, recipeID_123- the cake picture and recipe. That information is usually returned in a format called JSON. (It stands for Javascript object notation, which is not worth getting caught up in now). The application on the computer in the ‘cloud’ sends back an API response in JSON form that looks like this:
{ id: recipeID_123,
name: ‘decadent chocolate cake’,
image: ‘imageURL…’,
ingredients: ‘2 eggs, 1 cup flour, 5 tbs chocolate’,
description: ’best chocolate cake recipe passed on by generations’ }
Notice that all the information you need is contained in the response the server sends— the name, the image, the ingredients, the description. That response is then sent all the way back to RecipeX app, which is programmed to know how to present the recipe in a way that is convenient for humans to read, along with formatting, spacing, typography, colors, etc.
Now that you read that textually, lets look at it visually, in a nifty diagram:
See, RecipeX first displays a list of images. A user clicks on a cake image and sends a GET request, the server app receives the request, does the lookup of the recipe, and sends back a response with the recipe data.
To better understand how APIs work, let’s break something.
Let’s ‘break’ our API to understand it better
What if there was no recipeID_123 in the GET request? Once the app on the server looked up that ID, it would look for a matching ID in the relevant database, and find… nothing. There are two options now: for the server to return an empty response, or for the server to freak out, and ‘throw an error.’ Which will happen? That depends on the design of the API. So the human software folks get to decide how these computers talk.
Let’s change our API to understand it better
To get an even deeper sense of what an API is, let’s see another example of how the API could have been designed differently. Up until now it was:
GET /recipes/recipeID_123
What if the API was redesigned to:
GET /homeRecipes/baked/recipeID_123
See what is different? Instead of ‘recipes,’ the API takes ‘homeRecipies’, and the subcategory of ‘baked’ needs to be specified. What happens if the programmers designed the API in this way, and the RecipeX app didn’t know about it?
Well, the RecipeX app would send the GET request in the original way:
GET /recipes/recipeID_123
And it would reach the app in the server, and what would happen? An error. Because the application on the server only understands what the programmers defined in the API. The computers won’t be able to talk.
Exploring other API methods to enhance our understanding
So far we used cake to understand what APIs are, focusing on one type of API ‘method’, the ‘GET’ method which returns data. But what if you wanted to create a new recipe, and upload it to that website? You provide a name, image, ingredients, and description, and click ‘create’. And then what happens underneath the hood? Can we use the GET /recipe API for this?
If you guessed no, you’re right. We need a way to talk to the server and ask it not to retrieve (fetch) data, but to accept new data and store our recipe in the database. This is achieved by another method called ‘POST’. It’s the same idea as GET, but instead of asking the server to GET information, you’re asking it to take the information you’re passing, and keep it in the database. By writing up your recipe and clicking ‘create’ on the website, you would make a POST request like:
POST /recipes
This asks the server to take the information you are passing, and create a new recipe entry. In the POST request you are sending, you are also passing the data you filled out in a form. This, too, is done with JSON:
{ id: ,
name: ‘new recipe’,
image: ‘imageURL…’,
ingredients: ‘3 eggs, 2 cups oat flour, 2 tbs peanut butter’,
description: ’my kids favorite recipe’ }
When the server receives this request that you sent, it recognizes that you are asking to POST- asking it to create a new recipe entry to store in the database. It receives the data you want to store there, and if the fields you provided match up to the fields it can handle, then it will successfully fulfill your request — your recipe will be successfully uploaded.
Your RecipeX app will still get a response from that POST request, so that the server will tell us that everything went OK. That’s code 200. If something went wrong, then the API might be programmed to provide a different code response, and message. That is how you would know whether your recipe was uploaded successfully or not.
Now we see how computers talk, to create and store your new recipe.
There are other methods used in APIs. For example, if you wanted to edit a recipe- you can’t use GET, since we’ve seen that it retrieves information. You can’t use POST, since we’ve seen that it creates a new entry. So there’s a method called ‘PUT’ that can be used. Clicking edit recipe on the website, and changing the name, for example, would result in a PUT request, like:
PUT /recipes/reciptID_123
And you would provide the updated information.
Or, if you click to delete a recipe, then you have to use a new method:
DELETE /recipes/{reciptID_123}
This already covers the main operations, referred to as CRUD — create, read, update and delete. Remember what the API methods were for each?
Create → POST
Read → GET
Update → PUT (note, there’s also one called ‘PATCH’ for partial updates)
Delete → DELETE
Which API calls are used for which parts of each application? Well, technology folks have to decide what they want their applications to do (functionality requirements), and then developers have to decide how their services should do it — what methods to support, how each request should be handled, where the data should be stored, and what responses should be returned in what cases. For example, not all APIs need a PUT method — if they do not allow editing, there is no need.
Recap
Now it should make sense to you that ‘API’ stands for ‘Application Programming Interface’ — it’s the way applications talk. We covered how actions in apps work under the hood, by reviewing API methods like GET, POST, PUT, and DELETE. We understood how applications communicate, by sending messages back and forth, where our RecipeX app made a request, and the app on the server in the cloud received the request, did some operation, and provided a response. We learned about a popular way APIs communicate — JSON, and saw some examples of how data is shared. And what’s left now is to bake a Decadent Chocolate Cake.
Thanks for reading.
I hope this passed the ‘mom test’ and that you have a better sense of what an API is an how it works. When you are using an APP you can now appreciate a bit of what is happening back stage. If you want to learn more, you can go on to discover different types of APIs. We explored RESTful APIs in this article, which are popular.
.
About the author
I’m a UX Designer turned Product Manager, with experience in startups, freelance, and agile B2B2C companies. Writing helps me reflect & continuously learn. Connect with me on Twitter.
Other explanations of API
- This one by Flutter Queen is great for beginners
- This one by Petr Gazarov also includes technical explanation
- This one by AlexSoft gets into API types and use cases
