Explain By Example: API

Disclaimer: The following content is (yet again) not officially endorsed by Microsoft.

So I went to a party recently. Not something I thought I would ever talk about on LinkedIn but before I got to this party, I was thinking about APIs. Also not something one should think about before attending a party but that got me thinking about all the similarities between APIs and hosting a party...

When I first learned Java (an object-orientated programming language), I learned about the concept of Interface which is like a promise to do something. And I remember thinking, "Well, that's useless because promises are either empty or broken". But these kinds of promises in the programming world are actually quite important. I daresay they are almost as (if not more) important than those "swear on your pinky finger" type of promises that you made to your friend back in your childhood days. And like secrets hidden inside those promises, the implementation of an interface is abstracted away from you (hidden like a secret).

So why am I telling you this? Is it because I found out that you can deploy Java applications onto Azure? No, but that is pretty cool too. I told you that story because APIs is a type of interface that also promises something.

What is an API?

An API or an Application Programming Interface is a contract, a communication protocol, an interface that sits in between two systems that needs to interact with one another. You can think of it like someone saying, "You don't need to understand how I do it, trust me, I know how to do it and if you can speak my language, I will fulfill your request."

So let's go back to hosting that party. You need to provide catering, decorations, send out invites, find something nice to wear, schedule entertainment, book in facilities, etc. There are a lot of moving (and non-moving) parts to run a successful party. And if one part breaks down, then it's drama everywhere. The host is suddenly on the floor crying, the attendees feel super awkward. In a way, that is what operating and maintaining a large system feels like. When something breaks, IT is in full stress mode and scrambling for a fix and users or customers are often angry and looking for someone to blame. If someone constantly hosts bad parties, you probably wouldn't bother attending after a while. Similarly, if a system constantly breaks, no one would use it.

So why are APIs important?

Well, if you think about it, putting together a party from scratch will take a lot of work. Imagine if you had to bake your own cake, sew your own dress, stitch your own suit together, source your own rubber to make your own balloons, handwrite your invitations, and personally deliver these invites to each person. It seems a bit ridiculous to do everything from scratch, doesn't it? Similarly, it would be ridiculous to build any large software system from scratch.

What if, instead of baking a cake from scratch, you can just call up your local cake shop and ask, "Can I get a cake delivered by 5pm on the 23rd of February and here is what I want it to look and taste like" and then give them a list of requirements. Because this is a cake shop, they note down your request and will process it so that the perfect cake gets delivered to you just in time for the party. If, instead, you called up the cake shop and asked, "Can I get 50 invites delivered to these addresses?" they would most likely tell you that you have the wrong number and hang up on you.

There are many different outcomes when it comes to baking a cake. You can bake a perfectly good cake that looks and tastes exactly like the way you want and it comes out of the oven just in time for the party. Or, the more realistic scenarios (if I was in the kitchen), the cake could come out terribly burnt, under-cooked, or still cooking in the oven after the party has started. And if I was preoccupied with trying to set up balloons, sew my own dress, and put on makeup, I might actually forget to check on the cake and the oven could explode into a fire.

Because I want to host a good party without doing all the time-consuming and redundant tasks, I can call on other services to do it for me. And APIs allows me to do exactly just that which gives me time to focus on what is really important for my party; the party theme! The thing with APIs is that you are calling a service and you are promised some sort of outcome or result. But you don't know how this service is implemented behind the scenes. When you call up the cake shop and ask for a cake, they might respond with, "Yes, we can get this done" or "Sorry, we are at full capacity at the moment". What you don't know is what kind of oven they might use, what kind of recipe they are following, what ingredients they will use, who will bake your cake, etc. All you know is whether or not they can fulfill your request. You might be able to give them more specific requests like, "Can you make it dairy-free or gluten-free?" but how they actually put the cake together is completely abstracted away from you. Not only does APIs make our lives easier, they also promote re-usability and intellectual property.

• Reusable: If someone has already written a software component then I would probably re-use what they have written (and thoroughly tested) rather than completely rewriting the code myself. For example, I know for a fact that the cake shop makes better cakes than me so it would save me time and energy to use them to bake a cake for my party.
• IP: Because the implementation is hidden, often, APIs can even be monetized. Technically, it is the underlying service that API is calling that is monetized because they are providing a service. You know that saying, "There are no free lunches in this world". Well, that same saying applies to, "There are no free cakes in this world". So yes, I would have to pay the cake shop's CakeAPI to use their cake service.

Now, let's use APIs to put this party together:

You see how easily readable that is? Well, if you ignore the fact that this is Pseudocode (fake code), you can see how much simpler it is for me to put together a party using a bunch of API calls instead of doing everything on my own e.g. writing out all the code to implement all those features.

Speaking of parties and functions, there is a service called Azure Functions that is a type of Serverless technology that allows you to write your own code and execute runs based off triggers. It's like running a party without owning any infrastructure. Hiring a venue for a party is pretty common but you still have to check the place out, make sure the location and size is the right fit, make sure there is availability for the dates and times that you want, etc. And don't even get me started on the cleaning fees, the bond for venue damage fees, the terms and conditions that had to be 15 pages long.

Serverless technology is like going to a venue service provider and saying, "Give me a function room that can fit 50 people or more. I want it to be central to the city and available on the 23rd of February. Also, my budget is $500." And they will take care of everything for you so you can focus on the core logistics of your party.

The other Serverless technology that runs on Azure is a no-code, visual orchestrator called Logic Apps. I like to think of Logic Apps as a programmer who decided to become a designer but still wanted to code so now all the code they "write" is very visual. On the outside, it looks extremely easy but the things that it can do are extremely powerful.

Why did I bring up these Serverless technologies?

Because, these are both truly cloud-native ways to design, create, deploy, and consume APIs. Azure Functions can be used by programmers who want to write some hardcore customized API code and look extremely cool while doing it (like hackers in movies). Logic Apps is for everyone; the coders and the non-coders who still want to do hardcore stuff but don't have time to look extremely cool because they have a party to run.

Speaking of movies, imagine this party that I am throwing is for the Oscars. Now, my guest list has just become very high-profiled and everyone wants to come to my party. Not only am I making outbound calls (sending out invites, calling other APIs for their services), I will now also get inbound calls (media requests from TV agencies, news broadcasters, radio stations, journalist, etc) and because of my high-profile guest list and highly protected Academy Awards information, I need to be more mindful of who I talk to and what information I give them.

This is where Azure API Management comes in handy.

API Management can do many things, I won't go into all the technical details but the essence of API Management is that it can help you manage and distribute your APIs in a safe, secure, and easy-to-use environment. For example, a celebrity from the guest list might call up and ask, "Where is the after-party?" but this request could also come from an imposter imitating a celebrity to get information out of me. Using API Management, I can do things like filter who can send me requests and validate who they are before providing them with information. Because I know the media outlets will probably pay for this information, I can also monetize my APIs.

That's enough from me, it's time for you to go and have a party with Azure FUNctions and Logic Apps!

// Would love your comments, feedback, and any ideas on what the next topic should be :)Tweet me @mishxie or follow me for the latest blog updates and other random tweets!

P.S: If you want to support Explain by Example, you can buy me a coffee here ☕