APIs for dummies. Let's discuss!

ana profile image Ana Chiritescu Updated on ・1 min read

I was recently asked to be a speaker at a first meetup organized by a group of enthusiastic women that indirectly work with IT, understand that IT is becoming the core of everything we do and would like to learn more about this.

My plan is to talk about IT Systems, the importance of Integration and APIs.

Do you have any suggestions on how to best explain these concepts and/or talks/articles around it?

Moreover, depending on the time allocated for the talk, I might also go for a lightweight demo. The programming laguage used should be something super simple and friendly for non-techincal eyes! Any ideas?

Thanks a million for your comments! 😊


markdown guide

I'm not 100% sure what you mean by "Integration" (I can guess, but I'm not quite sure), so maybe start there by explaining that to me 😋

I'll have more thought once we get the semantics down.

As for languages: JavaScript has the huge benefit that everyone's browsers come installed with the runtime. So you'd just have to know how to show people how to open up dev tools. Otherwise, as far as I remember Macs come with Ruby installed and opening up an environment is as simple as typing irb into the shell, and then you could start with some simple commands like upcase and reverse etc. I think Ruby's quite friendly in this sense. If they don't have Macs, it's going to depend on other factors. Again, JS seems like the most accessible for this sort of thing.

As I write that I also feel like I'm probably out of touch in that you can probably use any language in an environment like repl.it/ so ignore the previous statement if you plan to do that. In either case, Ruby is still friendly.


Thanks, Ben! I'll have a look at repl.it.

Regarding what I mean by "Integration" (in the context of IT Systems Integration), I usually explain this is by making an analogy with bridges. As bridges connect roads, the "integration" connects systems. This is at a very high level.
On a more technical note this means building components that enable exchange of information between various systems. These components are most of the time part of the "Middleware layer" or the "ESB" (Enterprise Service Bus) and solve challenges like:

  • message transformation
  • message routing based on specific criterias
  • reliable delivery and more, with a focus on reuse.

While typing this I decided that for simplicity it is best to keep the topic of my talk around APIs only. I might touch the subject of IT Systems Integration as they are interconnected, but there is no need to mention it standalone.

Is my reply close to what you would have guessed? :)


Yeah, that's sort of what I figured. I agree with your approach of leaning more towards APIs and generally keeping it more simple. Sorry for the late reply. If you'd already done the presentation, let us know how it went!

I will share the presentation here in a couple of weeks. The talk is scheduled for November.


Hi Ana - one approach to consider is not talking about a specific programming language, but instead provide examples of how APIs and data integration are changing industries that 10 years ago nobody would consider hi-tech.

Retail, Agriculture, Manufacturing, Insurance - these are all examples of older industries that are hiring an increasing number of software engineers and completely changing the way they collect data, interface with customers, and connect with partners/suppliers. There are lots of API/Integration examples you can dive into that people will relate to. You can start with the "Every company is a software company" line, then provide examples around what that means.

Since you mention the audience is non-technical, you probably won't want to show them examples of actual code, however you can still get into the technology by discussing enablers of this transformation like sensors, wireless, open source, and the cloud.


Hi Ross! Thanks for your comment.
I very much like your suggestion of taking examples of older industries that are now going through the digital transformation and get into technology by covering today's transformation enablers! :)
Do you have good talks/articles on the topic that you would like to recommend?


Hi Ana - here is a panel from GitHub Universe 2015 that could be a good starting point:


It's a long video and I wouldn't necessarily be looking to it as inspiration for how to structure your talk. What it does contain that will be useful are very specific examples of how companies like Ford, GE, John Deere, and Target are using sensors, mobile, data, and API's to transform their businesses.

I could see taking these examples and building a presentation that tells a before and after story about how these industries have been transformed. You could also get into more detail around the nuts and bolts of APIs without getting too technical. Perhaps provide examples showing how sensors talking to gateways/interfaces, how that data ends up operational and analytic data stores. All of this ties back to your original premise that software/IT is changing everything.

Feel free to post your slides/outline before your talk if you'd like feedback on them.

Thanks a million, Ross! Will do!


As you mention in your comments below, stick with just API:s. A lot of companies are talking about API:s these days, but what they most likely mean are web API:s (and in most cases public web API:s), perhaps it's worth talking about this distinction. Also break API down into its parts and make it clear what each letter stands for and means. Some of my non-tech friends usually don't know what is meant by an "interface", let alone an application programming interface.

Try to find analogies to real world concepts and situations everyone can relate to regardless of background (your bridge analogy is a great example). Analogies are a great bridge (!) for understanding.

If you are going to demo something keep it as simple as possible (judging from what you write about your audience) and try to use something they can relate to or is really easy to get started with. For example Wikipedia's API and a simple web browser, and also provide examples of how another service could leverage Wikipedia (a travel app that gives you destination descriptions from Wikipedia?).

If you want to do something more tech than that the below are increasing levels of difficulty:

  1. invoke Wikipedia's API using Postman
  2. invoke Wikipedia's API using JavaScript from the browser console
  3. set up a mock api using json-server
  4. invoke your mock api using Browser -> Postman -> JavaScript

Agreed, when I first started I was very confused by what an API actually was. I would definitely provide at least 3 different examples in addition to spelling out the acronym. At the simplest level, a function could be used as a pseudo-example of an API and build from there. At least it helped me to think of it that way. Now I see pretty much everything as an API.


Thanks, Elijah! This time I will most likely not go much into detail around functions (it will be too technical for the audience). Interesting suggestion to look at a function as a pseudo-example of an API. Similarly one could see an APIs resource as a function, meaning that the API can have multiple functions.

Indeed everything is interconnected and the simplest/ideal way to do that nowadays is via an API or via an interface. There's one analogy for interfaces / APIs that I recently received as an example from a colleague that I find very easy for anyone to relate to: our own biological interfaces with the world, ie our senses.

Elijah, small clarification: my above comment on API resources as functions makes sense in the context of REST APIs. The simplification you mentioned is totally legit!


Rasmus, thanks for your comment! Glad you like my analogy with bridges. I agree with you, analogies are a good way to simplify understanding of what for others could seem abstract concepts.
One would argue that a bridge analogy points towards point-to-point integrations, however, I don't expect that to happen with a not very technical audience :-)
I've been working with APIs (not web APIs though) for a few years now, never crossed my mind to look into the Wikipedia APIs. Definitely a must check!
As soon as I will know more about the attending group, I'll decide on the right technical level for the talk and depending on that I might go for some of the other tips you shared. Stay tuned!


Hey Ana! I made a YouTube video about introducing APIs to beginners via Twitter bots. Though your audience may not be interested in building Twitter bots, they may find the first half of the video (in which I define & explain APIs) useful. ☺️


Hey Alaina! Nice, thanks for sharing! I will check it out! :)


Does the group have any professional commonalities? Were you given info on what the group hoped to get out of the talk?


Hello Monica, getting back to you as promised! Today I had a follow-up meeting with the meetup organizers and made more progress in defining the mission for the meetups and goal for the first event (that I am referring to in this post).
Here is an extract: "Our mission is to build a community of women where we share, engage and empower each other on various topics.
We are true believers that IT is everywhere and for this event we would like to show you a world of IT as we see it."
Anyone that attends the event will have their expectations set by reading this.
Overall, there will he women from various industries: finance, hotel services etc. Some of them Service Managers, Project Managers or Application Managers.


Monica, good questions! The group is very much unknown so far, it will become more clear closer to the event.
On what the group hoped to get out of the talk, I discussed this with the meetup organizers. Since it's their first event, as always, it tends to be challenging to start and/or set the purpose. I expect to find out more this week.


May I plug my article on this topic? I think you might find some useful ideas in it. dev.to/sztomi/respectful-apis


Thanks for doing so Tamás! Great article with strong and clear analogies, keep on writing. The video you mention in the article featuring Bobby McFerrin reminded me of my childhood hobby: piano playing (using heptatonic scale). I'll keep both in mind for the content of the presentation.