Part 1: Gentle Introduction to APIs for non-technical people… What is it? Why should we care ? And how to use them ?

Application Program Interfaces (APIs) have become an integral part of software development. The buzzword API is used in conjunction with pretty much every topic in the realm of computer software be it iOS apps, websites, back-end databases and so on.

As a Consultant in corporate America, I heard many people use the term API in a conversation, but often it seems their knowledge is somewhat limited. In this article, I hope to provide some clarity regarding the subject and most importantly provide an example of how APIs work in order to alleviate confusion around this ever present term — API.

NOTE: This article is part of the series. If you want to see only example of how APIs work, you can skip to Part 2. If you want to learn about benefits and use cases, you can skip to Part 3.

So, here are some of things I hope you will learn by the time you finish the article…

Want to read this story later? Save it in Journal.

Goals:

1. Learn what is an API, how it works, and definitions of the most commonly used terms in simple language (Part 1)
2. Learn how APIs work in the grand scheme of things (Part 1)
3. Understand basic API Principles and Documentation(Part 1)
4. Demonstrate a simple example of real world use of APIs (Part 2)
5. Discuss benefits & some use cases of API use in real life (Part 3)

Each section is organized by Goal number (#). So depending on what you are interested in, you can pick Goal that interests you. However, keep in mind that material builds on top of each other in some ways.

Goal #1: What is an API, how it works definitions in simple terms

First, let’s define what is an API and some of the common keywords used in association with APIs:

Informal Definition: An Application Program Interface (API) is a code that allows different applications to communicate with each other.

Example: Suppose you are creating a website and you want to have Google Maps in your website displaying different locations. Now, you have two options:

1. Create your own world map that will have similar functionalities like Google Maps
2. Use an external provider that already has created a map functionality and you just need to retrieve the information (i.e. get maps from Google Maps servers)

Now, let’s suppose you pick an option 2. The example above illustrates two important points. First, APIs is a software that will communicate with Google’s servers to retrieve the information you need. Second, because of APIs you don’t have to reinvent the maps application, but can simply use it because someone already created it. In other words, let Google Maps spend their time and effort building/updating maps, while you get to focus on creating something else ( your website).

Let’s define some more definition used with APIs:

• Requests & Responses

Earlier we defined how API is a software that allows communication between different applications. So, in this case, all of the communications are in the form of requests and responses.

Let’s use our earlier example of Google Maps. Every time, you want to open a Google Map, your website is communicating with Google Maps servers to get the necessary info. In particular, every time a user opens your website, your website will make a request to Google Maps server to get the view of the map. In reverse, that means that Google maps sends you a response based on your request. Each response and request has 3 digit code (e.g. 404, 200) along with some message. For example, if you made a request to Google Maps and got back:

Error code: 404
Message: Server not found

It means that your request wasn’t fulfilled and response you got was that the server (aka Google Maps) wasn’t found.

In the Goal #2, we will walk through response/request process in more detail — just FYI. More importantly…

Remember that API is nothing more but a code. API is not a server, nor a database, but a set of functions and procedures that gives an access to some server

Goal #2: How APIs work in grand scheme of things

Now that we have defined some terms, let’s look into bigger picture and discuss what is “communication” between different softwares.

Illustrated below is Figure — 1 which highlights the information flow between two endpoints when using an API. In this case, user is our first endpoint, and server with database (on the right-hand side) is the second endpoint.

More specifically, let’s follow numbers 1 through 7 that show step by step process of data flow when we make an API request. Assume that we are on the website and want to view our bank account information:

Step 1: Suppose user fills out a form (like login page) on the website to get access to personal bank account.

Step 2: Once user clicks on submit, the website will make an API request to bank’s servers and database

Step 3: API (software) that bank implemented will check if the incoming request has valid information to verify the account. In this case, API is a gatekeeper that will see if request has correct information to get access into bank’s servers and database

Steps 4 & 5: Server processes the request, which might entail pulling the user information, checking outstanding balance and so for.

Step 6: Once bank processes the request, the bank’s server will respond to the request and send user’s information back to where the request originated.

Step 7: Web browser (e.g. Chrome, Firefox ) will process the information and render it in presentable view.

Figure — 1: General data flow and communication between servers

Note that it doesn’t have to be limited to two endpoints, in reality it is more than 1. For example, when you are shopping for food delivery on DoorDash, the system used for payment might be used by Square, and Google Maps might be used for location.

Goal #3: How API calls work

API Documentation

Every time you think of using some API, you should think of documentation. API Documentation is a guide that will tell you what communications are possible and how exactly to request and responses work.

We already defined that APIs is a method of communication between two different software. If a word “API” is associated with word “communication”, the words “Documentation” should be associated with the word “method”. In other words, API documentation provides a description of method of how to make two softwares talk to each other.

In the Figure — 2, the graphic illustrates the documentation from the service called Zomato that provides information about restaurants (cuisine, open hours, price range, etc.). I picked this company from the list of open and free APIs and they had relatively well documented APIs for illustration.

Keep in mind that in the next section we will use Zomato service in our example.

In the Figure-2 (1. Snippet of Documentation) shows the overview of the structure and all the available API calls we can make. Let’s go over one of the API calls and see what information we have. On the right side, “2. Expand the view of an API Call”, we expanded /categories API call.

Once expanded, we can view the description of what this API does and see the type of HTTP Protocol (marked as 1 in red box). In the next section we will talk about API principles and HTTP Protocols. For now, note that each API call can be classified in one of the four options: GET, PUT, POST, DELETE. As you can see, all APIs present are GET commands.

In the box marked as 2, we see section “Parameters” that tells us what we need to provide to successfully execute the call. In this case, we only need user-key parameter which is API key we get when we sign up for service.

In the box marked as 3, we see all the possible responses that we can get and corresponding message when we make API request from this service.

Figure — 2: Sample API Documentation view & main components

There are more that we can cover in API documentation, but for the purpose of introduction and demo in Part 2, you should know these 3 points.

RESTful APIs, its principles & HTTP Protocols

Most often than not, when people talk about APIs, the are referring to RESTful APIs. They are most widely used type of web development architecture.

In order to be considered RESTful APIs, the API must adhere to certain principles to be considered valid. For the purpose of this article we will discuss only HTTP Protocols — GET, POST, PUT and DELETE

Figure — 2 on the right shows the table of HTTP Protocols with short description for each operation.

Let’s revisit example from Goal #2 about user submitting credentials to login to view outstanding balance.

In this example, we read information from bank’s server and database, which means we sent out GET request to bank.

Broadly speaking, every time we are communicating via APIs, we need to include one of those four words on what operation we would like to do.

For example, suppose you made a purchase to buy some food and swiped your card. In this case, the money must be withdrawn from the bank account. As withdrawal of money will result in change of outstanding balance, that means that PUT HTTP Protocol will be used to make this specific API.

Retrieve the Information

At this point, we have 1) looked at the API documentation of the service we want to work with and decided that their service is good enough for our use cases.

Next step is to start retrieving the information from the API service provider. In general, working with APIs can be broken into 4 generic steps:

Step 1: Sign up on an API platform of your choice (& provide payment info if required). Once this step is complete, they will usually provide API Secret Key, which serves as your identifying information on their servers (for billing and to keep track of API calls)

Step 2: Retrieve information from API service using preferred method. For example: terminal, 3rd party GUI and/or use a programming language

Step 3: Parse and store retrieved API information

These steps are broad, but they are pretty much universal when it comes down to working with any APIs.

In conclusion, so far we accomplished 3 Goals where we

1. defined what is an API and defined some terms.
2. looked into how APIs transfers data and
3. defined how APIs work.

In the next section (Part 2) we will perform above mentioned 3 Steps using Mac’s terminal, Talend API (3rd Party GUI), and Python

Next Up: Part 2: Coding Example to demonstrate how APIs work

Thanks for reading my article. Check out my other stories. If you liked it, or have any comments/questions, let me know! Feel free to connect on social media: Instagram, GitHub, LinkedIn.

📝 Save this story in Journal.

👩‍💻 Wake up every Sunday morning to the week’s most noteworthy stories in Tech waiting in your inbox. Read the Noteworthy in Tech newsletter.