Lifecycle Walkthrough

Every other guide in this documentation explains one feature. This one does the opposite: it carries a single small API through the whole cycle — design it, mock it, test it, document it, hand it to an agent — so you can see where the pieces meet.

The point of doing it in this order is that each stage produces the input for the next one. You design a contract; the mock is generated from that contract; the tests assert against that contract; the documentation is that contract; the agent reads and edits that contract. Nothing here is copied by hand from one stage to the next, and that is the whole idea.

What you need: a project, and the permissions of an Admin or Owner. On the Free plan every step below works, with the caps noted where they apply.

The example: a tiny Bookmarks API with two operations — GET /bookmarks and POST /bookmarks. Substitute your own; the sequence does not change.

The five stages run in that order, but their dependencies are not a chain — almost every one of them reads the same contract:

flowchart TB
    D["You design it<br/>API Design"]
    C{{"The contract<br/>a released version, its schemas"}}
    M["A mock of it<br/>Mock Server"]
    T["Tests against it<br/>Testing"]
    P["Docs generated from it<br/>Documentation"]
    A["An agent that edits it<br/>MCP server"]

    D --> C
    C -->|"one rule per endpoint"| M
    C -->|"imported cases, schema validation"| T
    C -->|"the API reference"| P
    C -->|"the same objects, your permissions"| A
    M -->|"its base URL becomes the environment"| T
    A -.-> C

1. Design the contract

Open API Design in a project and create a specification — Empty Specification for this walkthrough, or Import if you already have an OpenAPI file, a Postman collection, or an Insomnia export.

Add the two endpoints:

1. In the endpoint tree, click + → Add Endpoint.
2. Method GET, path /bookmarks. Add a summary — it becomes the label everywhere else.
3. Repeat for POST /bookmarks.

Then give them a shape, because everything downstream depends on it:

• On GET /bookmarks, open Responses and describe the 200 — a Bookmark array.
• Create the Bookmark schema once under Components and reference it from both endpoints, rather than describing the same object twice. This is what makes the next four stages consistent.
• On POST /bookmarks, define the request body and a 201 response.

Two things worth doing now rather than later: run the style guide over the spec to catch naming and consistency problems while it is two endpoints rather than fifty, and release a version once the shape settles — a released version is frozen, which is what gives the mock, the tests and the docs something stable to point at.

In depth: Endpoints · Schemas · Style Guide · Spec Versioning

2. Mock it, before any backend exists

Open Mock Server in the same project and choose From OpenAPI spec. This creates the server and generates a rule for every endpoint in the spec in one step — including GET /bookmarks and POST /bookmarks, each answering with data shaped like the schema you just defined.

The server has a public base URL of the form https://abc123de.routebasemock.dev. Copy it from the workspace header.

That URL is the deliverable of this stage. A frontend developer can start against it on the same day the contract was agreed, without waiting for a backend — which is the reason to design the contract first at all.

Two refinements that pay off immediately:

• Add a rule that returns a 4xx for a specific input, so the error path is buildable too, not just the happy one.
• Use Try It in the API Designer with Mock Server as the target to confirm each endpoint answers as intended before anyone else builds on it.

In depth: Mock Server · Mock Server Settings

3. Test reality against the contract

Testing needs somewhere to point. That is an environment: open Environments in the project and create one — call it Mock — with the mock server's base URL from the previous stage as its Base URL.

That one field is the join between stage 2 and stage 3. Test URLs are written as {{baseUrl}}/bookmarks, and {{baseUrl}} resolves from whichever environment is active. The same suite that runs against the mock today runs against staging tomorrow by switching the environment in the header — no test is edited.

Now build the suite:

1. Open Testing and create a suite, e.g. Bookmarks API.
2. Use Import in the suite toolbar to bulk-create cases from your spec's endpoints. Each imported case arrives with assertions derived from the contract rather than written by hand.
3. Run the suite with the Mock environment active.

The assertion that matters most is Schema Validation, which comes with cases linked to a spec endpoint. It validates the response body against the endpoint's documented schema, so a field that changed type or a required property that went missing fails the run — even when the status code is still 200. That is the difference between testing that your API answers and testing that it still honours its contract.

When the real backend appears, create a second environment pointing at it and run the same suite. Anything that passes against the mock and fails against the backend is a place where the implementation and the contract disagree.

In depth: Environments · Test Suites · Contract Testing

4. Publish documentation that cannot drift

Open Documentation in the project. On the first visit, Routebase offers a three-step assistant:

1. Content — name the portal and tick the spec you want embedded as an API reference. A draft-only spec is published on the way in.
2. Branding — choose the portal address (a subdomain) and a theme.
3. Go Live — publish. The portal is built and you land on its live URL.

The API reference is generated from the spec, not written alongside it. When the contract changes, you publish a new documentation version and the reference follows — there is no second copy of the endpoint list to keep in step. Hand-written pages live in the same tree, so conceptual guides and generated reference sit together.

If you set up a deprecation plan in stage 1, its banner appears on the affected endpoint's page here, with the sunset date and the migration guide — which is how a consumer finds out without anyone sending an email.

In depth: Documentation Overview · Publishing · Custom Domains

5. Hand it to an agent

Everything you just built is reachable by an AI agent through the Routebase MCP server, which every workspace has — nothing to install and nothing to host.

Point your client at https://mcp.routebase.dev. Claude clients add it as a custom connector and sign you in with your Routebase account; Claude Code, Cursor and VS Code connect over HTTP with an API key; anything stdio-only uses the routebase-mcp bridge.

With that in place, an agent works on the same objects you have been using: it can read the spec, add an endpoint, generate mock rules, run the suite and report what failed, or update a documentation page — under the permissions of whoever authenticated, not above them. An API key carries only the scopes you gave it.

This is the stage that changes how the earlier ones feel. A contract that an agent can read and modify is worth keeping precise, and a test suite an agent can run is worth keeping green.

In depth: MCP Quickstart · MCP Authentication · Resources & Prompts

What the cycle looks like on the second lap

The first pass is linear. After that it is a loop, and the loop is where the value sits:

For larger changes, do them on a branch and merge them after review, rather than editing the main draft directly.

Next steps

• Keep an eye on the live API with Monitoring.
• Scan it for the OWASP API risks under Security.
• Run the suite in your pipeline with the CLI or a scheduled run.