Spec-Based or Code-Based: Which Mock Server Do You Need?

APIGit has two types of mock server. Every mock server is one or the other, and you choose when you publish it. The short answer is to start with spec-based. Here is how to tell when you need code.

The difference

| | Spec-based | Code-based | |---|---|---| | Source | One or more OpenAPI documents | Scripts in apigit-mock/ | | You write | Nothing beyond the document | JavaScript (Express.js) | | Responses | Examples from the document, or generated from its schemas | Whatever your code returns | | Request validation | Built in, and configurable | Your own code | | Stays in step with the spec | Always: the document is the mock | Up to you | | State between requests | No | Yes, with the state object | | Plans | Free, Team, Enterprise | Team, Enterprise |

Choose spec-based when the document says enough

If your API is described in OpenAPI, a spec-based mock gives you a working, validating server in about a minute, and it cannot drift from the spec. It suits frontend teams building against an API that does not exist yet, and partners who need a sandbox. Declared errors are one header away: Prefer: code=404.

Choose code-based when answers depend on something

Choose code-based when a response must depend on earlier requests, or on logic the document cannot express: a multi-step checkout, an OAuth flow, a computed price.

A code-based mock runs the scripts in your repository's apigit-mock/ folder. mock is an Express.js 4 app, so you get mock.get(), mock.post(), mock.use() and the rest of the Express API, and state persists between requests:

mock.post('/users', (req, res) => {
  state.users = state.users || [];
  state.users.push(req.body);
  res.status(201).json({ count: state.users.length });
});

Libraries such as @faker-js/faker, lodash and jsonwebtoken are pre-installed. Your code runs in an isolated sandbox with no network access, so it cannot call outside services. The apigit-mock/ folder can be 2 MiB zipped, and state can be 2 MB. You do not have to start from nothing: Generate from Spec in the Mock Scripts tab writes routes from an API document, and the code is yours from then on.

You can have both

The type belongs to each mock server, not to the repository. One repository can publish several mock servers of either type, from the same commit or from different ones: a spec-based mock of openapi/petstore.yaml for the frontend team, and a code-based mock of a stateful checkout flow, side by side.

A mock server keeps its type when you overwrite it. To change type, publish a new mock server. Each mock has its own URL, so you can run both while clients move. Moving from code to spec usually means adding example values to your document for the responses your scripts returned.

What each plan includes

| | Free | Team | Enterprise | |---|---|---|---| | Mock servers | 1 | 10 per seat | 20 per seat | | Mock server calls per month | 1,000 | 2,000 per seat | 4,000 per seat | | Documents per spec-based mock | 1 | 10 | 10 | | Code-based mock servers | No | Yes | Yes |

Read more in the Mock Server overview and How code-based mocks work.