Mock Server Overview

A mock server gives your API a real URL before the real service exists, so frontend, mobile and partner teams can build against it while the backend is still being written. In APIGit, a mock server is published from your Git repository and runs on APIGit Cloud at https://<name>.mockserver.apigit.com. There is nothing to host.

Two types of mock server

Every mock server has a type, chosen when you publish it:

Spec-based (the default, on every plan): answers from OpenAPI documents or GraphQL schemas. OpenAPI mocks match HTTP operations and use examples or generated bodies. GraphQL mocks validate queries against SDL and generate values for the selected fields. You write no scripts.
Code-based (paid plans): runs the Express.js scripts in your repository’s apigit-mock/ folder, so responses can be computed, stateful and as elaborate as you need.

	Spec-based	Code-based
Source	OpenAPI documents and/or complete GraphQL schemas	Scripts in `apigit-mock/`
You write	Nothing beyond the document	JavaScript (Express.js)
Responses	OpenAPI examples or generated bodies; GraphQL values shaped by the schema	Whatever your code returns
Request validation	OpenAPI checks are configurable; GraphQL queries are checked against SDL	Your own code
Stays in step with the spec	Always: the document is the mock	Up to you: regenerate or edit the scripts
State between requests	No	Yes, with the `state` object
Several APIs on one mock	Yes, each document under its own base path	One Express app
Plans	Free, Team, Enterprise	Team, Enterprise

A mock server is one type or the other, never 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. For example, a spec-based mock of openapi/petstore.yaml for the frontend team and a code-based mock of a stateful checkout flow can sit side by side at the same commit.

Which one should I pick? Start with spec-based for OpenAPI or a complete GraphQL schema. The hosted mock validates requests and generates responses from that source. Choose code-based when responses must depend on earlier requests or on logic the document cannot express, such as a multi-step checkout, an OAuth flow, or a computed price.

How a mock server stays up to date

A mock server always serves one commit. You decide how that commit changes:

Pinned to a commit (the default): it serves that commit until you publish it again.
Following a branch (paid plans): it is republished automatically at every update of the branch. If an update cannot be published, it keeps serving the last good commit.

See Pin or follow a branch.

What each plan includes

Spec-based mocks are available on every plan. Team and Enterprise add code-based mocks and branch following; Enterprise lets you choose the mock server’s name. Hosted mock counts and monthly call allowances are account-wide, rather than per seat. Paid plans can add monthly call packs.

See pricing for current allowances, fair-use ceilings and call-pack prices. Hosted GraphQL mocks are included in spec-based mocking. AsyncAPI mocks are not supported.

Code-based mock servers that a Free account published before this rule keep running. You can still edit their settings and delete them, but republishing one needs a paid plan. An account that moves to Free keeps its code-based mocks on the same terms, and a mock that was following a branch stops updating until the account is on a paid plan again.

Try a mock on your machine

Before publishing, the apigit command line can run spec-based mocks (an OpenAPI file, or a GraphQL schema since CLI 0.7.0) and code-based mocks locally, offline, using the same engines as their hosted versions:


npm install -g @apigit/cli
 
apigit mock serve openapi.yaml       # spec-based, OpenAPI
apigit mock serve schema.graphql     # spec-based, GraphQL at /graphql
apigit mock serve apigit-mock        # code-based

See Run a mock on your machine for what differs from a hosted mock.

Next steps

Quick start: publish your first mock server and call it
Publish: every option of the publish dialog
Documents and base paths: serve several API documents from one mock
GraphQL mocks: publish a schema and query generated data
Responses: how a spec-based mock chooses what to answer, and how to ask for a specific response
How code-based mocks work: the Express.js runtime, built-in routes and limits