DEV Community

Cover image for What is an API?

What is an API?

Rémi Mercier on May 23, 2019

Feeling queasy about explaining APIs to your grandma 👵 or a non-technical client 👔? Lemme help you out! Before we start, I’d like to ask you a fe...
Collapse
 
jmplourde profile image
Jean-Michel Plourde • Edited

What a great post Rémi!

I always kind of knew the role of an API but didn't grasp the concept enough to explain it in simple terms. You did it brilliantly. I really liked the lamp metaphor. It goes straight into my mental models.

Collapse
 
mercier_remi profile image
Rémi Mercier

Thank you Jim for the kind words!

Collapse
 
jmplourde profile image
Jean-Michel Plourde • Edited

Just to add a bit more as a good to know: Your electricity provider do care about the design of your lamp. If your lamp returns current to the grid (I will spare you the wave-function math behind) it damages it. Electricity providers use Fourier transforms to evaluate how much your appliance is damaging the network and they charge you money accordingly. Fortunately, this problem mostly concern the industry field.

Thread Thread
 
mercier_remi profile image
Rémi Mercier

That's interesting! Didn't know 1) electricity went back to the grid 2) that it harmed the grid 3) that providers were charging you for it. There's a lil' something to learn every day on dev.to. 🥳

I'll dig on Fourier too. I've its transforms but it's remote from my usual interests so it's kinda hard to grasp at first (so I guess I won't write an article on the subject anytime soon! 😄)

Collapse
 
steelwolf180 profile image
Max Ong Zong Bao • Edited

Awesome article on the part of standardisation.

I think it should be more of in the form of contract(API documentation).

Which both parties has to agree upon to use the API.

Therefore if either parties breaches the contract.

The repercussion is it won't work or behave abnormally with a valid reason by either parties on why the contact is breached.

No one will enter a contract if it is not favorable for both parties to be in a partnership to work together.

Collapse
 
mercier_remi profile image
Rémi Mercier

Yes, the contract was (and still is tbh) an API concept I found difficult to understand. May be because a lot of public APIs have a very loose understanding of contract breach (ie no backward compatibility). But again, not-so-well-known APIs upon which a lot of hardware is built fell into the contract category.

Your explanation is 👌 Max and made it much more graspable to me.

Collapse
 
steelwolf180 profile image
Max Ong Zong Bao

Actually, it took me a while in working with a frontend developer that made me realise the importance of it.

I found out later that either you create your own contract by yourself or you could use existing template contract like OpenAPI Specification to facilitate and make your life easier for API development.

Thread Thread
 
mercier_remi profile image
Rémi Mercier

Yes yes, Swagger is awesome. I've only beginning to use APIs that use Swagger, and it's neat.

Didn't realize it was a contract, though 😅. But now that you pointed it out, this seems obvious!

Thread Thread
 
steelwolf180 profile image
Max Ong Zong Bao • Edited

Hahaha check out Postman, It's a godsend and allows you to import OpenAPI files into Postman to make your life in creating APIs easier.

I believe the new release of Postman allows you to create your OpenAPI specs as well.

Collapse
 
joshuakahn profile image
Joshua Kahn

Great piece Remi. A friend of mine produced this video when we were on Best Buy's Open API team years ago. The idea was to produce a really simple and effective explanation of the attributes of open api's that make them so powerful. There's a little bit of the 'lies told to children' thing happening, but if you need to actually explain API's to your grandma, it's pretty great.

Check it out: youtube.com/watch?v=7r7QpIDEI_o

Collapse
 
mercier_remi profile image
Rémi Mercier

Will check it out! Thanks for sharing Joshua!

Collapse
 
liyasthomas profile image
Liyas Thomas

Great post. Feel free to use open source API testing tool: Hoppscotch to spin up these APIs on-the-go directly from your browser window and get to know about how APIs behave when requested at client side.

GitHub logo hoppscotch / hoppscotch

👽 A free, fast and beautiful API request builder used by 100k+ developers. https://hoppscotch.io

Collapse
 
thefoxboxman profile image
John De Costa

Great work Remi. Excellent metaphor. Keep up the brilliant writing, love your style

Collapse
 
mercier_remi profile image
Rémi Mercier

Thank you John for the kind words!

Collapse
 
carlosalfarodev profile image
Carlos Alfaro

Nice way to explain API's! Thank you!

Collapse
 
tmpou1 profile image
Thomas P

Good job Rémi 🚃 !

Collapse
 
mercier_remi profile image
Rémi Mercier

Thanks Tom! 😉

Collapse
 
node_srojas1 profile image
saul rojas

Thank you for the information, and the great metaphor 🤙

Collapse
 
banzyme2 profile image
ENDEESA

A SET OF UTILITY METHODS USED TO COMMUNICATE TO EXTERNAL SOFTWARE LIBRARIES? CAN BE CALLED DIRECTLY OR VIA HTTTP ENDPOINTS IN MOST CASES

Collapse
 
angelarae63 profile image
Angela Whisnant

Perfect! Thank you!