From Mock to Real

Your consumers call one address — the gateway your API is published on — and that address is where your API lives regardless of what is answering behind it. A stand-in generated from your contract, or your own service in your own cluster: from outside they are the same API at the same URL, with the same credentials.

So the transition is not a migration, and there is no separate switching step to learn. A deployment carries where traffic should go. Deploy a contract without naming an upstream and it answers from the contract; deploy it naming one and it reaches your service. Going live is the same call you already made, with a field filled in.

It is POST /v1/apis/{id}/deployments. Leave the upstream out and the deployment answers from the contract:

curl -X POST https://core.api.apiway.net/v1/apis/{id}/deployments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "oasId": "...", "apiEnvironmentId": 3 }'

Name one and it reaches your service. defaultTargetServer applies to every operation; targetOverrides names a different upstream for individual ones:

curl -X POST https://core.api.apiway.net/v1/apis/{id}/deployments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "oasId": "...",
        "apiEnvironmentId": 3,
        "targetOverrides": [
          { "method": "GET", "path": "/orders", "targetServerUrl": "https://orders.internal" }
        ]
      }'

So you do not have to cut over all at once — and the operations you have not moved yet are still answering statefully from the contract, not failing. That half-and-half period is the one an assembled stack finds hardest, because it is where a temporary backend and a real one have to be kept consistent by hand.

You do not flip a switch. The work of building the implementation is tracked like any other work, and when it is released the upstream moves from the stand-in to your service as part of that release. Nobody has to remember to do it, and nobody can do it early — the release does not happen until the checks on that work have passed.

It is also not an untraceable configuration change. The decision is an approval flow, and the context it was decided against is recorded with it. Months later the question “when did this stop being a stand-in, and on whose authority” has an answer, which is not true of somebody editing a target in a console.

None of which requires you to adopt a delivery process. Releasing an implementation is not a different mechanism — it makes the same deployment call, from a work item instead of from you. Your own script, your existing pipeline, a completed piece of tracked work: three triggers, one request. If your team already has a way of working, it keeps it, and if it has none it does not need one.

Nor does it mean a queue of people. Who has to agree comes from the template the flow runs, and those range from approving automatically to requiring several named reviewers. A two-person pilot picks the automatic one and moves at the speed of editing a field, with the record still written. A bank picks a different one. The same release mechanism serves both, and you change your mind by changing the template rather than by changing how you deploy. See Approval Flows.

That is the point rather than a side effect. Where your consumers’ traffic is sent is the most consequential setting an API has — change it and every request goes somewhere else, with the same URL, the same credentials and nothing visible from outside. A field anybody with access can edit is exactly the wrong shape for that. Making it an outcome of a governed release means it cannot be done quietly, cannot be done by mistake, and cannot be done without leaving a record of who decided and what they decided against.

Why it is invisible

Your consumers never receive your specification. They receive one written for them, in which the servers are the gateway they call rather than anything of yours — and their access, their limits and their credentials are laid over the top of it, per subscription, at the gateway.

Your deployment sits underneath all of that, and changing it does not disturb the layer above. This is the same reason onboarding a consumer does not require you to redeploy, and the same reason a consumer’s terms can change without your service knowing. Replacing the stand-in with your implementation is one more change underneath a layer that was built not to notice.

What your consumers keep

Base URL	Unchanged
Token endpoint	Unchanged
Client id and secret	Unchanged
Scopes	Unchanged
Paths, methods, shapes	Unchanged — they come from the same contract

Nothing they wrote needs editing, redeploying or re-credentialing. If you have given a partner a URL and a credential, that URL and that credential keep working.

What does change, and must be planned for

Being straight about this is worth more than the reassurance above, because each of these has caught somebody out.

Data does not come with it. Anything a consumer created while the stand-in was answering lives with the stand-in. Identifiers they stored will not exist in your service. Tell partners to expect a clean slate at cut-over, or give them a window to recreate what matters.

Behaviour the contract did not describe appears for the first time. The stand-in answers from the contract, so it is as complete as the contract is. Validation your service performs, business rules, conflicts, anything conditional — a consumer meets those at cut-over. This is the honest cost of starting before the implementation exists, and the way to shrink it is to describe more in the contract rather than less.

Operations that are not simple reads and writes. The stand-in is convincing for resources you create, fetch, change and remove. A search with ranking, an action that triggers something, a long-running job — expect these to behave differently once your service answers.

Integrate partners against the environment that will serve them

Each environment has its own gateway, its own URLs and its own credentials. If a partner integrates against development and your service then goes live in production, their base URL and their credentials change — not because of the switch, but because they were pointed somewhere else all along.

The switch preserves everything. Moving between environments does not. If partners are going to build against the stand-in, put the stand-in where they will eventually be served.

If the contract changes while partners are integrated

It will. That is the point of showing partners something early — they read it properly and tell you what is wrong with it.

A change that does not break anything goes to the version they are already calling, and they carry on. A change that would break them cannot go there: it is not permitted onto the same proxy, and becomes a new major version with its own path. Your partners keep calling the one they integrated against, unchanged, until they decide to move.

So design iteration does not move anybody’s URL underneath them. It creates a second one, and the first keeps serving until it is retired deliberately.

If a deployment fails to reach the gateway at all, it rolls back on its own. Whatever was serving before carries on serving — a failed publish is not something your partners find out about.

The host is the one thing worth deciding early

Everything above is about what stays the same. The host is the exception, and it is worth settling before anybody integrates rather than after.

You can publish on a hostname you own — api.yourcompany.com — rather than on the gateway’s. It is a field on the API, and it moves the whole surface: the base URL, the OpenID discovery document and the token endpoint all answer on your domain, with no path prefix. See Your Own Domain.

That is also the honest answer to what happens if you leave. An address your partners hold that belongs to us is something you would have to migrate them off. One that belongs to you is not.

The same applies if you run production traffic on a gateway you already own: the host your consumers call is that gateway’s, not the one the stand-in answered on. Everything else about the contract, the credentials and the scopes still comes from the same place.

A sensible sequence

1. Deploy the contract. Consumers can call it immediately, answering from the contract.
2. Turn on dynamic mock data so what they create is still there tomorrow.
3. Give partners the URL and credentials for the environment that will serve them in the end.
4. Build the service against the same contract.
5. Deploy again, naming your service as the upstream. The stand-in stops answering, your service starts, and nobody outside is asked to change anything. Name it for some operations and not others if you would rather move in stages.

There is no step where somebody edits a live target by hand, which is deliberate: a cut-over that arrives as a deployment is one you can point at afterwards and say who released it and when.

See also: Mock Data · Quick Deploy · Environments