Explaining API Management to your mom

In this blog post we’re going to cover what are all the parts of API Management using an example based on a restaurant. We all too often forget that not everybody is technically-minded, and sometimes it’s great to take a step back and find common language to explain certain terminology.

So what’s your job again?

Nice to meet you all, I’m Antoine, a Product Owner of the Gravitee.io API Management solution, you can find me on our community forum. One of the biggest challenges I’ve met so far is to answer my mom’s question, “What’s your job all about?”.

I guess my normal answer would be, “Product Owner of largest Open Source API Management mom. We’re creating software to build, monitor and secure APIs! Did I also mention it’s Open Source? Isn’t that awesome!?”.

However, that didn’t seem to convince her that much, nor did it help her understand what I'm doing with my day. But she’s my mom, so she loves me anyway and she’ll get along with “my son works in IT”. I’m looking for a change - I don’t want to fix printers anymore, and I guess my mom deserves to understand what I'm working on. A thought to consider, do we really understand our areas of expertise if we can’t even explain it to our mom, or a six-year old for that matter?

And so comes the tricky question: how do I explain what API management is to my mom? I’ve been trying to figure out some sort of approach. I’ve been:

• Diving into my school archives to find relevant resources
• Exploring howtocode.com
• Looking at the basic tenets of IT, and so on.

Do I really want to give my mom a four-hours lecture on the basics of APIs? I’m not so sure. Does she want to listen to a four-hour lecture? Hmmm not sure either. Is this going to work with a six year old? Definitely not!

What’s needed is something that’s tangible, based on a real-life situation that can aptly describe the purpose of API Management. So, let’s run with the example of a restaurant - everyone can relate to a restaurant - even my two-year old son has mastered the art of ordering fries.

The restaurant analogy

Photo by Jeremy Bishop on Unsplash, and as you can see I’m not a designer ;)

Client/Customer - It’s rather funny that we use the same term in API Management! Coincidence - I don’t think so! The client application is what sends a request. How would they go about making their request? Are you going to a restaurant and asking for whatever you want? Most certainly not, you will ask for a menu.

The API Specification or definition is the equivalent of a menu in a restaurant. It contains a list of what you can order, and a description of what you can expect for each item.

The backend of your application is the equivalent of the restaurant’s kitchen. The kitchen will prepare your meal, dish it out and nicely present it on a plate, and with a bit of luck, give you exactly what you ordered. This is the backend’s responsibility - to provide you the information you need, apply any processing to the data, and maybe request more information from other sources. The kitchen would handle the food processing, for example freezing, defrosting, slicing, dicing and cooking. The kitchen may need to request more ingredients. All of this information and processing going on, you, as a client or customer, do not need to know about, nor should you care about it for you to receive your ordered dish!

So we now have a customer (client), a menu (API specification) and a kitchen (backend system). We are missing one key element here. How does the kitchen know what you want? Sure, you could go into the kitchen yourself and directly ask the chef, but he’s nervous, and doesn’t really want to be speaking to lots of people during the dinner rush hour. Also, it’s not particularly hygienic to have people coming into a kitchen, nor is it practical for 30-odd patrons to walk in, shouting out their preferred order. So, how do we deal with taking the order from the party of 10 who’ve just turned up, as well as trying to keep the children across the room not crying out for as long as possible? The waiter!

Waiters are the equivalent of APIs. The waiter goes to the customer to get their order, and brings it to them. They will also:

• Prevent overconsumption (in my opinion, two dishes are plenty)
• Offer adaptations if something is unavailable on the menu (we’re out of smoked salmon, but the smoked trout is an excellent alternative)
• Adapt the request timing and arrival in specific cases (let me bring some bread to your kids right now)

When the dishes are ready, they’ll also provide the appropriate cutlery for the meals, as well as delivering an overall expected experience. A waiter works very much in a similar way to APIs between your requests (the order off the menu) and the responses (the meals delivered to your table). There are a number of things that happen when you make requests and responses (called policies in API speak), such as:

• Help secure your API calls (sorry, you’ve had enough to drink)
• Apply data transformation (let me cut up the meal for your child)
• Get some more information in order that the backend can do its stuff (do you have any allergies the kitchen should be aware of?)
• Processing a response (you’ve ordered the soup, I’ll bring a spoon)

How do APIs know how to handle these cases? Sure, there are common topics - security, data transformation for example, but how do we deal with specific organization policy? Let’s get back to our restaurant example. There are many common tasks (taking orders and delivering them), but the restaurant may have some specific policies to handle queues, both of customers waiting to get in, and the orders themselves, giving priority to certain orders, or perhaps just having certain ground rules that need to be applied to the restaurant in general.

API Management is the equivalent of our restaurant manager, or Maitre d’. The manager will define how the waiters (APIs) will work between the kitchen (backend) and the customers (clients). The manager can also analyze customer flow (monitor global traffic) and how everything is being handled. They will follow up on all the orders, as well as managing how customers are billed for their meal (API monetisation - If you’d like to know more, check out this post by our dear Linus, VP of Product). In addition, API Management can take a more holistic and bigger picture view of what’s going on in the restaurant, and look to make the waiters (APIs) jobs easier. For example:

• Hire a bouncer at the door to check if patrons are too drunk to be served alcohol (gateway security and/or integrate access management, e.g. Gravitee AM)
• Provide standard policy all waiters follow in relation to hungry children (gateway caching)
• Raise awareness of what’s not currently available on the menu and suggested alternatives ahead of time (gateway dynamic rerouting)

Summary

Drawing from our restaurant analogy, in summary:

• Restaurant - our system architecture
• Customer - the client application
• Menu - the API definition
• Kitchen - the backend application/service
• Waiter - the API
• Restaurant manager/Maitre d’ - the API Management system

We’ve covered in this post how i would explain my job to my mom, and I hope if you’re in a similar tech role such as development, architecture, marketing and UX, you’ll appreciate the importance of being able to find a common vocabulary to explain our background, our concepts, our jokes, and ultimately our culture. It is a lot harder to work with each other if we’re not able to share and understand each other. I feel that, as a product owner/manager/team, we’re the bridge (or should I say, the gateway... hmmm hmmm API Management joke) between people.

Final thoughts

In my scrum team, we talk all day long about gateways, proxies, virtual hosts, processors, reactive development, fixing printers (haha, no chance!) and all those weird and wonderful terms. Can you imagine the faces of our User Experience team when we initially explained to them that we need a new user interface for virtual hosting? It goes the same way when you’re helping users - what are they trying to achieve? It matters not that they’ve got an issue with a specific protocol setting (bugs outstanding), what I really want to know is why they're using the product in this way.

What’s the best way to achieve this outcome? The best advice I've seen so far is to act like a six-year old. Keep asking why. Why? Why? Why? It forces you to really understand what is behind the surface - the 90% of the iceberg, and avoid misunderstanding. Don’t assume that your explanation is simple or straightforward. We all have different backgrounds and you want to make sure they have the same understanding of the concept as you do. If you can explain something to a six-year old, that means you really know your stuff!

Be a six-year old!