API Mocking Guide and Online Mock API Server Testing

The fastest way to understand what’s possible with an API is to send it requests and review the responses. During the initial design of an API, it can take weeks to have live calls available. You can develop against an API in parallel by creating mock API servers to return example results. Furthermore, you can create a better API by getting feedback sooner and iterating before writing code to serve a production API.

A mock API server imitates a real API server by providing realistic responses to requests. They can be on your local machine or the public Internet. Responses can be static or dynamic, and simulate the data the real API would return, matching the schema with data types, objects, and arrays.

A mock API server is useful during development and testing when live data is either unavailable or unreliable. While designing an API, you can use mock APIs to work concurrently on the front and back-end, as well as to gather feedback from developers. Our mock API server guide for testing covers how you can use a mock API server so the absence of a real API doesn’t hold you back.

Often with internal projects, the API consumer (such as a front end developer through REST APIs) moves faster than the backend team building the API. This API mocking guide shows how a mock API server allows developers to consume a working API with the same interface as the eventual production API. As an added benefit, the backend team can discover where the mock API doesn’t meet the developer’s needs without spending developer time on features that may be removed or changed. This fast feedback loop can make engineering teams much more efficient.

You can also use mock APIs to emulate APIs you don’t control. For example, you can use a local mock server to fake results from a public API when you aren’t connected to the Internet. Or, use mock data responses if live calls to an API would incur a charge from the provider.

You might also mock API calls for unit testing. When your tests run with every deploy, you may not want to wait for dozens of live calls to an external API. A mock API server or library can return anticipated results so you can unit test the rest of your code. Keep in mind, you’ll want another method for ensuring that API responses meet expectations, such as API contract testing.

Before you create a mock API, make sure you understand what type your project needs. There are advantages and drawbacks of each kind. How you use it will be determined by the needs of your project and how realistic you need to make your responses.

At its simplest, your mock API can use static example responses for each endpoint. You can generate these yourself, store them from an existing API response, or use a tool to provide dummy data. The drawback to a static response is that real APIs produce different data based on different input. You may not get realistic results in this case, such as missing fields in responses. In addition, some field types, such as dates, will not have realistic values over time

In contrast, a dynamic response can make your mock API more realistic. The data can be randomly generated based on the type of field and requirements you determine. You can even allow for different results based upon input, such as including search terms in results or calculating dates from parameters.

Another distinction of your mock API will be whether it is mocking an external dependent API or your own. You likely will expect more changes to your own API, especially if it’s still in development. Make sure you have a way to keep your mock servers updated, such as generating them from an OpenAPI Specification (formerly known as Swagger Specification). We’ll discuss methods of generating data in the next section.

External APIs also change, of course. Unless you have access to their API definition, your ability to keep the mocked responses updated is limited. The best approach is likely to periodically gather live results and store them for use by your mock API.

Finally, some mock APIs are fully staged on public servers, while others are created only for your local machine. When publicly accessible, you can more easily tie them into services and tooling hosted elsewhere. However, local mock servers might be advantageous for unit tests and other situations requiring low latency or offline access.

The major requirement of a mock API REST server is to generate the data to send as responses. Ideally, the data is realistic, because you want to make the experience as close to a real API as you can. However, an overly complex effort to build a mockAPI may negate its purpose. In the cases where the real API is available, the mock API is meant to unblock projects that depend on the API, not become a project itself. We will cover all these points in this dummy REST API mock data and mock rest API definition guide to address the question of what is a mock service or mock REST service.

When generating mock data, you can use static responses or fully randomized fields. Depending on how you create advanced REST API mock data and mocking REST services data, you may also be able to find a middle ground of mostly static content with some fields dynamically generated.

The most basic way to create a mock API server or mock REST API is to use static responses which we will cover in this advanced dummy mock API data definition, mock data definition and dummy web service APIs for testing guide. The downside of this approach is returned data is potentially repetitive and outdated, which breaks down the illusion of real data. However, if you need to quickly create a mock API by hand, you can connect it to a basic web server.

With the static approach, you can grab a response from an existing or similar API and then make edits manually. Typically, response formats are JSON or XML, so you’ll need to be familiar with the syntax. Your text file will need to emulate the same structure of fields that the real API will return.

You will need a basic server to return the appropriate data for your mock calls. If you don’t have a go-to API server, consider some popular API frameworks:

• Hapi (Node)
• Falcon (Python)
• Flask (Python)

An alternative to wholly static responses is to generate static data from code. You already need to use a small amount of code to return the text content, so you could instead hard-code your mock data into your dummy server. There are a couple advantages to this approach: You can selectively include dynamic data (such as future dates) and you won’t have to worry about data format syntax. You can represent your dummy data as a hash or dictionary, then use your framework or programming language library to return JSON or XML.

However, even these partially-dynamic mock APIs require manual input. If you have described your API using a format such as Swagger, RAML, or OpenAPI, you have more options to create dynamic mock servers.

As design-first APIs gain popularity, API descriptions become an important way to share what’s possible. You’ll also find many tools built around these formats, most notably the OpenAPI Specification. An OpenAPI document provides a machine-readable description of exactly what is possible with your API. The OpenAPI definition becomes the source of truth throughout the API lifecycle, starting with the earliest design.

Many of the top API experts have gathered around this central format, based on the Swagger format. The OpenAPI Initiative is a consortium of industry supporters creating a standard (using YAML or JSON) to describe the mock API endpoints, responses, and other parts of an API. From this one document, you can generate example responses or even build entire mock servers.

There are major advantages to using an API description instead of one of the manual data approaches:

• Automatically generate data from schemas
• Share descriptions with any consumers of the API
• Utilize the description to generate documentations, tests, and more

Plus, you save yourself the manual effort and potential for outdated mock data.

Once you have an OpenAPI document to describe your API (you can create one in , you can plug it into an open source data generator or a mock server service.

Stoplight Mocking provides hosted Prism servers based on OpenAPI documents imported into or created with our API design tool.

If you have example responses in your OpenAPI definition, those will be used. But you can force dynamic mocking to always generate the data based on your spec.

In many cases, you’ll want to make your mock server available publicly. Whether the API consumers are co-workers, external partners, or even your own code, it can be helpful to provide Internet-accessible mock servers. You can use many of the methods described in this guide, such as the basic dummy server stub code or a hosted mocking service.

Unless you are hosting an open source tool like Prism, you’ll likely be generating your endpoints and data manually. Building from a single source of truth, like an OpenAPI document, will allow you to generate realistic responses automatically.

Robust mock servers return more than dummy data. Rather than static responses, which are either handmade or copy-pasted, a powerful mock server will create dynamic data from OpenAPI definitions.

Manual mock servers can seem like extra work. They may temporarily unblock the developer using your API-in-progress, but the data returned by a static mock server may become dated and inaccurate. When generating from an OpenAPI description, your mock API servers can generate data to include in the latest interface. By being up-to-date, you will receive better feedback from developers, improving the speed you can iterate on changes.

OpenAPI-driven mock servers also save you time by generating common objects in your API from a single model. For example, the schema for your resource may return an ID (an integer) and a name (a string). Your mock server uses this schema for all endpoints that generate a single instance of the resource. Additionally, it’s just as easy to generate multiple instances for endpoints that contain an array of the resource. Stoplight Todos shows a sample mock service in action.

Mock API servers are a very useful part of creating and using APIs. However, they’re just one part of a larger project that often includes collaborators across an organization. Stoplight can help you at each step with tools for designing, documenting, and testing your API.

You can import an existing OpenAPI definition, or create one from scratch with our visual designer. See how Stoplight’s mocking helps you share mock servers with your team in minutes.