DEV Community

Cover image for Explain API in Plain English
Somnath Singh
Somnath Singh

Posted on • Updated on

Explain API in Plain English

Have you ever heard the word “API,” and wondered exactly what it is? Do you have a vague idea of what it does or what it is used for?

This is something that you will encounter when you first start programming with any sort of web technology. Many newcomers struggle with this concept, and many get some vague ideas about it and assume that they know what it is.

Now APIs aren’t exclusive to web programming but it’s something that you use a lot when you are programming for the web or mobile. In the past, APIs were largely associated with computer operating systems and desktop applications. In recent years though, we have seen the emergence of Web APIs.

What is an API?

It stands for Application Programming Interface. This sounds scary and fancy at the same time! What does that mean? What exactly is an API?
Like most places, I won’t give you a vague definition, full of technical jargon.

So, here it is:

In a nutshell, API is some code that you didn’t write yourself, and that code has some methods that you are allowed to call. It could be something that you download and run from your computer or it could be something that’s someplace else on the web.

That’s all an API is, in its essence.

Don’t think anything else, when we say an API just stick with the definition mentioned above!

Is that’s all it is? In its essence, Yes.

Then why such a fancy name?

Lets find out!
Let us build an API in JavaScript that will enable us to cook our dinner 🍜(virtually ofc).

Our API Code that is stored in the computer

As I said, we can have APIs that are local on our computer or saved in a remote server, or it could be something that you can download. We have made one locally and named it API, but it can be named anything.

It is a JavaScript file that I’ve downloaded and saved into a local folder.

When I run my webpages, I’m able to use this piece of code:

There is an immediately invoked function expression(IIFE) that is going to run itself.

At the very bottom, it’s going to return an object, and the object that it’s returning has three properties.

We can call these methods using a dot operator.

Calling methods described in our API.

When will call these methods in a row, we get an output like this:

We have function steamVeggies() that calls other function addSpices()

Here addSpices() can’t be called directly but I can call steamVeggies() which will then run the function addSpices()

Now what this is doing is just console logging out some messages, it’s not important what’s being done, what is important is that I have an object with a name. This would be one file that I can download and use, or it could be saved on a remote server, or it could be something that I download and keep with my files, then in my script file, I can use that.

So, I could say API then dot, and here are the things that were returned from this function.

These are the methods that we can call:

We could say, alright I’m going to call the function step1() and then I need to call the function step2()

There are other ones in the API like addSpices() that we can’t call one directly.

calling this one would give us an error

So there’s code inside there that’s hidden away from us. We don’t know what it is doing, but some things are exposed to us, which are public . We can access those in our code. I can use a step1(), step2() and step3(). These are the things that are available to us from the API.

In the Application Programming Interface, the Interface part of it is these three methods:

This is the Interface part of the code

Those methods are the interface for me, to interact with this API

This is our Application Programming part of the code

Now, does it make sense why it is called Application Programming Interface?

Now, above we have used the name API, but it doesn’t have to be called API. It could be called anything. You can call it Som if we want.

What you need to understand is that there is this black box hidden away from us. What we know is from the documentation. It says these are the things that we could use and we use those in our program.

That’s all an API is. Code that somebody else has written, that I have access to, that I can use in my code to accomplish some sort of task.

It can be sitting on a remote server,

It can be sitting on my own computer,

It could be something that I have to use HTTP to talk to, I have to make an AJAX requests to the API to get information back.

You may encounter the term RESTful API while doing web development. Don’t get confused, It is also a code but it follows a certain architectural style and uses HTTP requests to access and use data. That data can be used to GET, PUT, POST and DELETE data types, which refers to the reading, updating, creating and deleting of operations concerning resources.

But in a nutshell, It is just code that somebody else has written to make our life a little bit easier!

APIs in the context of Web

APIs are to the Internet what switchboard operators were to early telecommunications!

Like how switchboard operators used to connect calls, APIs enables communication between applications or software. An API or application programming interface is a part of a remote server that receives requests and sends responses when you navigate to a website in your browser.

Take for example, A request for data goes out to Medium’s remote server. Once your browser receives the data and processes the code response, the browser displays Medium Page. In this case, Medium’s server is the API that enabled communication and allowed you to access the webpage.

What is happening here is that your request goes to a code that someone else wrote and stored on the server. It provided you access to the current page that is stored somewhere in the remote server.

Your request doesn’t go to the server directly! It goes to an API, and that API decides what to do with it.

Client(left), API (Blue bolt), and Server(right)

API are also enables interaction and data alteration between two sites like when a webpage has a share to Twitter button, clicking this button triggers communication with your Twitter account, and alters your account by adding a new Tweet.

Now, this code or API can take many forms depending upon where it is being used. It will get a name respective to that area. To name a few, we have

  • Open APIs or Public APIs: These are publicly available to developers and other users with minimal restriction.
  • Partner APIs: These APIs exposed by/to the strategic business partners. They are not available publicly and need specific entitlement to access them.
  • Internal APIs or Private APIs: These are hidden from external users and only exposed by internal systems. It is not meant for consumption outside of the company but rather for use across different internal development teams for better productivity and reuse of services.

Bird’s eye view 🦅

Beyond the difference between internal, partner, open APIs, we should mention another approach to categorize APIs:

  • Data APIs provide CRUD access to underlying data sets for various databases or SaaS cloud providers.
  • Internal service APIs consist of exposing internal services, reflecting parts of internal processes, or some complex actions.
  • External service APIs are third-party services that can be embedded into the existing services of the company to bring additional value.
  • User experience APIs leverage composite APIs to help app developers provide the right experience for each specific device (desktop, mobile, tablet, VPA, IoT).

APIs may be further classified as local, web, or program APIs:

Local APIs is the original form, from which the name came. They offer OS or middleware services to application programs. Microsoft’s .NET APIs, the TAPI (Telephony API) for voice applications, and database access APIs are examples of the local API form.

Web APIs are designed to represent widely used resources like HTML pages and are accessed using a simple HTTP protocol. Any web URL activates a web API. Web APIs are often called REST (representational state transfer) or RESTful.(We discussed it above)

Program APIs are based on remote procedure call (RPC) technology that makes a remote program component appear to be local to the rest of the software. Service oriented architecture (SOA) APIs, such as Microsoft**s WS-series of APIs, are program APIs.

API examples in the developer community

Companies like Facebook, Google, and Yahoo publish APIs to encourage developers to build on their capabilities. These APIs have given us everything from new internet features that browse the sites of other services, to mobile device apps that offer easy access to web resources.

New features, such as content delivery, augmented reality, and novel applications of wearable technology, are created in large part through these APIs.

Next time, Whenever you hear of the word API, Think of it as a code that allows two software programs to communicate with each other by running back and forth between applications, databases, and devices to deliver data and create connectivity.

What we have learned

  • API is some code that you didn’t write yourself, and that code has some methods that you are allowed to use.
  • In context of web, an API is a part of a remote server that receives requests and sends responses when you navigate to a website in your browser.
  • API can take many forms depending upon where it is being used for example Open APIs or Public APIs, Partner API, Internal Or Private API.
  • It can further be classified into Local API, Web API, Program API.
  • In short API is code that allows two software programs to communicate with each other.

Now, I hope you have a clear understanding of what an API is and its various nuances. I have seen people struggling with this term. Looking at it from a broader perspective will put an end to the struggle, that people have while learning this fancy term, which they call an API.

If you still have any questions, you can ask them in comments or reach out to me on my Twitter. 🙏

If you found this article helpful in someway then consider sharing it with others. Let me know your views on it, because to me it matters!

Take Care! See you in my other post!

Top comments (0)