This is the Age of the API (Application Programming Interface). No matter what type of software you work with, you will likely have to deal with APIs on some level. When a developer visits an API website, you will see plenty of documentation, sample code, use cases, and endorsements that make you feel one click away to start consuming. However, there is something that can convince you more than a website can: watching an amazing live API demo.

If you are on the other side of the story and have your own API, you must prepare an API demo. Your API must compete for attention and then convince others that — among all the existing alternatives — it is the best solution and is worth trying. Usually the Developer Evangelist is the person jumping to the floor with a laptop to rock the stage with their API demo at a hackathon, meetup, or conference. If you are a developer building APIs, it’s likely that sooner or later you will have to demo your API at these sort of events as well. Whether you’ve done it before or not, knowing the best practices is invaluable.

After observing a large number of great API demos — from amazing to dull — the best, most unforgettable API demos have the following six points in common:

1: Tell what the API is all about, in few words.

Finding a clear and concise way to describe your API is an obvious first step. Great demos introduce the API in a very concrete way, starting with real situations. Speaking in abstract terms is out of question, and in practice it’s very easy to get lost in acronyms (HTML, REST, SOAP, JSON, etc) and developer jargon. You must answer the question “Why does your API exist in the first place?” Using metaphors, stories, or examples of people with real names can be helpful aids. The optimal explanation isn’t either too long or too short, like in this example where SendGrid’s Swift explains SendGrid API in a nutshell:

“SendGrid is an API company that makes it super simple for you to send and receive emails from your applications. A turnkey solution for any time you need to deal with anybody’s email on your app: password resets, alerts, etc.”

2: Convince we all share the same values of the API

This is an easily underestimated point. Doing it will make sure you have identified a connection between you or your company and your audience: we have the same struggles and we all are developers creating amazing software and applications to solve people’s problems. Developers attend hackathons and technical conferences to learn and try new things, and often to discover solutions to challenges that they already face.

Convincing the audience of a shared value will create a stronger emotional bond than just ending the demo saying “you’re welcome to try our API”. In a presentation with Nordic APIs, Ronnie Mitra does a fantastic job of establishing shared values by reinforcing the importance of user experience design with a worst case presentation scenario — great acting!

3: Impress with how great and easy your API is

There are many aspects that make an API outstanding, such as easy onboarding, usability, scalability, maintainability, security, stability, support, and compatibility with other major solutions. However, even if you API excels in all these areas, some are too abstract for a brief demo.

An unforgettable API demo is created as a performing show that in addition to educating will entertain people. One of the requirements is that the code looks really easy and short. A good way to measure the length is asking yourself: do I need to scroll down the screen? A great example is the demo by Twilio’s John Britton. Pay attention to the simplicity of the code. That really impresses. This demo created a conference call that could be joined by anybody ringing a randomly selected local number. This short demo ends capturing and displaying the full list of phone numbers of the participants (Surprise!).

4: Interact with the audience

Even though these types of demos are usually short (less that 10 minutes, even as short as 3 minutes), just watching a text-based code editor can be boring. Great demos involve the audience. There are many ways to do it: ask participants to take their own gadgets and open a webpage, write and send either an email or SMS, ask to cast a vote, look at your camera, shout, etc. One of the most accomplished demos is again by Twilio’s John Britton, who interacted with dozens of participants.

A strong reason to interact with the audience is that API demos often force the speaker to stand behind a lectern. Have you noticed this? In contrast, think of how many times you have seen a TED talk speaker behind a lectern. That’s indeed very rare. Interaction breaks the barrier that is almost inevitable in every API demo.

5: Live coding mastery

“Talk is cheap, show me the code” —Linus Torvalds

Certainly the main element of an API demo is live coding. Live coding mastery involves a number of good practices that when put together produce amazing results. Some elements are:

1. Making your code short. The live code itself must be very short (1 minute in total, which can imply 2 or even more sections) and leave the rest of the time for the audience to see the results, and even interact with the outcome.
2. Make it easy to display code on the screen. Rehearse in advance to see what is the best way to display your code. This will involve the choice of your code editor, the color of text and background (usually black characters in white background are the best), and even the fonts. Take into account that the quality of the projector, screen, and lighting of the room will affect how your audience sees your code.
3. Explain what you are writing in sync. Say in a clear way what every line you write is going to do. It will help tremendously if the names of functions are self-explanatory. Needless to say, if you already follow good coding habits, this is easier.

6: A theater-like script

If you ever performed in theater, you must have learned and memorized a script by heart, maybe adding your own interpretation to the lines. For an API demo, similarly prepare a step-by-step script for yourself. Why this is so important? You must know exactly which parameters you will use for every example — the order of steps makes a huge difference. The successful guys who have had memorable API demos are all said to have rehearsed the same sequences dozens of times. Some claimed to have even dreamt about it.

Another huge advantage of using a written script is that it makes your demo repeatable. If your next meetup isn’t for a few months, you don’t have to rely on your memory to start preparing yourself again. An API demo is a play, not improv.

An extra piece of advice is: reduce the number of steps to the minimum, and minimize the number of parameters. All this will reduce the probability of failure.

Preparation for potential technical flaws

Things we don’t see also matter. It’s highly recommended to have a list of technicalities in advance. Some of them can be checked well in advance and others when you are at the venue. Normally we don’t see it, but a well-prepared developer will do this before the API demo. It can save you from a disaster and help you to recover quickly.

Here’s a list of items that would have a big impact if they fail:

A final piece of advice is: time yourself and stick to the allotted time slot. The most successful API demos are short and to the point. So, when it’s your time to rehearse, set an optimal time length and repeat the demo until you and the chronometer are in sync.

Conclusion

Following these six best practices and preparing for potential flaws will make your API demo unforgettable, and will make you or your company’s end goal of stimulating developer adoption more realizable. Great demos have the power to transform a technical event into an enjoyable, memorable, and inspiring experience. Ultimately, it will inspire developers to build great things with your API, which will bring value to end users. Feel free to share other amazing API demos in the comments section and tell us why they were unique.

We wish you a successful next API demo. It’s API time. It’s showtime!