Let’s face it; the current approach to building APIs is busy. We want to deploy everywhere, scale quickly, and automate as much as we can. No doubt, this presents some new challenges. In particular, how are we supposed to build against APIs that are incomplete or unstable?

API emulators are an up-and-coming solution to this problem. In this article, we’ll introduce you to some of the basic concepts of emulators, including what they are, how you can use them, and how to get started with building your own.

What Is an API Emulator?

As the name would suggest, an API emulator mimics the functionality of your API. The job of an emulator is to provide predictable responses against which developers can build, even if the API itself is unavailable or constantly changing.

For an emulator to be useful, you don’t need to implement your API’s entire set of features. However, you do need to implement at least one complete use case.

Emulators vs Mock Servers

Mock servers are another popular choice for recreating the functionality of an API. Unlike emulators – which usually run on your local machine – mock servers are servers. This means that you have to spin up a new server for every mock server you create, often relying on third-party tooling to do so.

Neither option is necessarily superior, but there are some circumstances where one fits better than the other – more on that later!

Steve’s Webex Emulator

Steve says he first experimented with emulators when building a chatbot for Cisco’s collaboration tool, Webex Teams. He built and deployed a bot that would respond to webhooks provided by Webex, but it didn’t work as intended.

Unfortunately, there was no easy way for Steve to test the behavior of his code since it relied on Webex webhooks. His only options were to deploy new services continually, or to build a tool that would emulate the webhooks provided by Webex, at will…

And so the Webex API Emulator was born! If you look into the documentation, you’ll see that the emulator’s primary use case is “to test and debug Webex chatbots.” As a result, it mimics only the resources necessary for that use case: /rooms, /memberships, /messages, /attachment/actions and /webhooks.

Steve demonstrated the tool during his talk. Within just a few clicks, the emulator was up and running. Emulators don’t usually have a graphical user interface, and Steve’s was no exception: Emulator started on port: 3210, the command line read.

Then, Steve moved over to a Postman instance where he could send requests to the emulator, with localhost as the API’s URL. The responses are exactly what you’d expect from an API — check out this example using the /people/me endpoint:

{
        "id": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS85MmIzZGQ5YS02NzVkLTRhNDEtOGM0MS0yYWJkZjg5ZjQ0ZjQ",
        "emails": [
            "stsfartz@cisco.com"
        ],
        "displayName": "Stève Sfartz",
        "nickName": "Stève",
        "firstName": "Stève",
        "lastName": "Sfartz",
        "avatar": "https://cdn-images-1.medium.com/max/1600/1*Iel5Q6qAxgBdl_IHUx3scA.jpeg",
        "orgId": "Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi8xZWI2NWZkZi05NjQzLTQxN2YtOTk3NC1hZDcyY2FlMGUxMGY",
        "created": "2017-07-18T00:00:00.000Z",
        "type": "person"
}

To implement webhook functionality, Steve used a second tool called ngrok to create a secure URL for accessing his computer. Then, he set the target URL of the Postman webhook to this ngrok URL. After pushing a message to his emulator from Postman, Steve was able to open up the ngrok admin interface and see his webhook being fired.

That was all it took for Steve to launch a Webex API emulator that would allow him to test his bots thoroughly. Once again, you can see the full inner-workings of the emulator on GitHub.

Why Use an Emulator?

Following Steve’s short demonstration, it’s immediately clear that there are a few reasons why you might consider using an emulator.

For starters, emulators are great for testing. You can launch the emulator in a matter of milliseconds, and don’t have to worry about managing real-world API constraints like rate limiting.

Next up, emulators can help with quality assurance procedures. For example, if you have a cloud service that changes over time, it’s bound to start behaving differently. An emulator can bring benefits such as non-regression and versioning, so you can know precisely how code responds to older iterations of your service.

Another benefit of emulators lies in API design. Instead of directly implementing new features in a production API, product managers can add that new functionality to an emulator with significantly less technical overhead. Then, developers can easily test out the new behavior and provide their feedback before editing the production API.

The final benefit: using an API emulator doesn’t require internet access. So, if you want to work on your application while camping in the wilderness, that’s now possible!

Advice for Building Your Emulator

Although building an emulator might sound pretty daunting, it’s easier than you think. Steve said he’s made emulators in just two days, and he was kind enough to share some advice on how you can do the same.

Most importantly, Steve recommends you think big, but start small. Start by implementing one full use case. So, don’t spread yourself too thin: focus on the use cases you especially need.

Next, keep it light – after all, that’s why you’re building a mock, and not just another API. He recommends keeping the application in-memory.

Finally, he suggests using a low-level HTTP framework so that you can freely tweak payloads and headers. This allows you to mimic your API’s behavior as accurately as possible. Steve used Express.js for his emulator.

Final Thoughts

If you’re an API provider, Steve believes you should consider API emulators as part of your API product strategy. Emulator development shouldn’t take long (you should aim to build an emulator in hours or days, not weeks). They could massively help your developers build against a few specific use cases.

Best of all, if you open-source the emulator, both your internal developers and your developer ecosystem will be able to (and likely will) contribute something useful. Oh, just don’t forget a “best effort” disclaimer!