The gateway needs a model of your backend
Part B chose a tier. Whether you then created a real instance or are following the desk path with the supplied contract, the gateway so far knows nothing. Before it can throttle, authenticate, or route anything, it needs a model of the backend it is fronting: which operations exist, at which paths, with which verbs, expecting which inputs, returning which shapes. In APIM that model is an API — a named collection of operations, where each operation is one verb at one path, exactly the GET /products/{id} shape 38a taught you to read. The gateway does not need to understand what a product is; it needs to know that this operation exists so it can attach policy to it, count it, and forward it.
This is the first place the front-desk metaphor gets concrete. The gateway publishes its own URL — campux-apim.azure-api.net/catalog/products — and maps each operation to a backend address. Consumers who use that gateway URL need not know the backend URL. This is useful indirection, but it is not access control: 38f and 38g show how to restrict direct backend calls.
Import the spec; do not retype it
You can create operations manually, but an existing OpenAPI specification is a useful starting point. Import can create supported paths, methods and definitions for APIM to display and route.1 It does not import or enforce every OpenAPI feature: Microsoft documents ignored security definitions and limited OpenAPI 3.1 support. Validate the file first, inspect the imported operations, configure authentication and backend routing separately, then test real requests.
| Source | When | Cost |
|---|---|---|
| OpenAPI import | A validated spec exists | Imports supported operations; review limitations and results |
| Azure resource | Fronting a Function App, App Service, or Logic App | Wizard reads the resource and wires the backend |
| WSDL / SOAP | A legacy SOAP service must be exposed | Imports and can even present it as REST |
| By hand | A tiny API, or a mock with no backend yet | Fine for two operations; a maintenance tax at twenty |
- OpenAPI import
- Creating an APIM API from supported portions of an OpenAPI document. Review the imported model, set security and backend routing, and reimport or redeploy when the source changes.
Keep the OpenAPI file in the repository and import a reviewed version through a pipeline when that fits the team. Reimporting is an action, not automatic synchronization: a stale file or skipped deployment can still let the gateway and backend drift. Compare the deployed operations with the backend and run contract tests before publishing changes.
The backend, made a first-class thing
Where does the gateway forward a real request? To a backend — the service that does the work. APIM lets you represent it as a named, reusable object instead of repeating its URL across operations. That object can hold the service address and connection details. If several operations use it, you can change the configured address in one place. Test the route after any move; a new region or private endpoint may also need network and identity changes.
A named backend gives the gateway a stable configuration point while the underlying service address changes. Consumers can keep calling the gateway hostname if the public paths and behavior stay compatible. That does not hide or secure a backend that remains publicly reachable; use network controls and backend authentication to prevent bypass.
Mock responses — a contract before a kitchen
APIM can return a mock response without forwarding to a backend. Its policy uses an example from the API definition when available, can generate a sample from a schema, and may return an empty body if neither exists.2 This lets a frontend or partner test request wiring against an agreed example while the backend is still being built. Tell consumers which operations are mocked and which behaviors the example does not simulate.
For a staged rollout, agree on the contract, import it, attach a documented mock and let consumers build against it. Before switching to the real backend, compare status codes, headers, validation, error cases and response bodies with the mock. Run integration tests with actual clients, then cut over gradually. A shared OpenAPI file reduces drift; it does not make the cutover automatically invisible.
For this partner onboarding design, attach the API to a protected product and publish that product so partners can discover it in the developer portal and request access. Publishing is about discovery: Microsoft notes that APIs in unpublished products can still receive gateway requests, and APIs can also be configured without a subscription requirement. Set access and authentication deliberately before sharing an endpoint.
The forgotten spec earns its keep
In this fictional case, Campux reviews the catalog OpenAPI file and imports its supported operations into a Standard v2 gateway. The team checks parameters and examples after import, then configures the named backend and access policy. A pipeline can repeat that process after reviewed spec changes, but tests still have to catch differences between the file and the running service.
The partner contract adds two fields the current backend does not yet return. Campux provides documented mock examples while the backend team builds them. Before exposing the real response, it tests the new fields, errors and authorization with partner clients. The mock saves waiting time; it is not proof that the real service will behave the same way.
Play it through
Arrange one documented rollout for an API import, then decide how to bring in a later operation. Other rollout orders can work; the checks after import are what protect the contract.
This part uses a no-cost simulation. A real APIM tier can incur charges; use the current pricing calculator before trying an instance in Azure.
An API with shape, not yet behaviour
At this point the gateway has an imported API model and either a named backend or a mock for the operations in this example. The protected product supports partner discovery and subscription. Authentication, rate limits, caching and backend network restrictions still require explicit configuration and testing in later parts. Do not assume an imported security definition has already enforced them.
Unblocking three teams with one mock
If the backend is weeks away, agree on the OpenAPI contract and publish a clearly labeled mock with representative success and error responses. Mobile and web teams can begin integration work in parallel. When the backend is ready, run the same contract and workflow tests against it before cutover; a sample response cannot prove production behavior.
Continue with a supplied build
Follow the same fictional catalogue through this track. The supplied contract and worked checks let you practise without an Azure estate; the optional import/mock path makes real gateway requests. Each step states what it proves and what it does not.
Examination
Four drills, then two situations. The situations have no marking scheme — write your answer before you reveal the reasoning, or the exercise is worthless. Nothing is stored; this is between you and the page.
B — one reviewed source can feed repeatable imports. A pipeline can reduce manual drift when the OpenAPI file is current and the import succeeds. It cannot prove the backend implements every definition, and APIM does not process every OpenAPI feature. Inspect imported operations, configure policies separately and run contract tests after each change. Manual operations can also have policies and appear in the portal; the benefit is a reviewable process, not automatic correctness.
B — a mock can unblock consumer wiring. It returns an example or generated response without calling the backend. Consumers can start on request shape and documentation, but a mock does not reproduce all validation, errors, authorization or data behavior. Test those against the real backend before cutover. A mock is neither a cache nor a load test.
A stable gateway hostname and named backend can keep backend address changes out of a consumer’s contract. That works only if consumers use the gateway and the public API paths stay compatible. The backend still needs authentication and network controls, because merely omitting its URL from documentation does not make it private.
# onboard catalog API to APIM
1. Import the API from the OpenAPI spec in the repo,
via the Class 22 pipeline.
2. Point operations at a named backend so the real
address lives in one place.
3. Put the backend's real URL in the partner
integration guide too, as a fallback.
4. Mock the two new fields until the backend adds
them, so partners aren't blocked.
Line three undermines the intended access path. If partners use the backend URL as a fallback, gateway limits and logs no longer cover every call. Keep the public contract at the gateway and restrict direct backend access. A pipeline import and a named backend are useful, while a documented mock can help early integration; each still requires configuration and tests.
Grant that hand-clicking feels faster in the moment, because it does. For the first import, twenty operations by mouse is a real hour and the spec import has a small setup cost. If the whole story ended today, your teammate would be right — so do not argue about today.
A hand-maintained copy of an existing contract can drift when the backend changes. Put the reviewed OpenAPI file in the repository, import supported definitions in the deployment pipeline, and compare the resulting APIM operations with a running backend. If the file itself is stale or an import feature is unsupported, the pipeline alone will not catch the mismatch.
Offer to automate the import and add a contract check. That makes the change repeatable and gives the team evidence about what was deployed. It may take more than one line of configuration, but the review and test are the value.
Reject the premise, because the choice is false. "Wait or fake" assumes the only real thing is the backend. It is not — the contract is real, and it can exist and be honoured before a line of backend code does. So the answer is neither: I agree the OpenAPI contract with the partner first, and treat it as a deliverable.
Agree on an OpenAPI contract and publish a clearly labeled mock for supported success and error examples. The partner can build request wiring while the backend is in progress. Before switching to real forwarding, test actual responses, authentication and failure paths against the agreed contract. Shared documentation makes parallel work possible; it does not guarantee an invisible cutover.
Tell partners which endpoints are mocked, which behavior is not simulated, and when the real service will be available for testing. Keep the mock and backend implementations aligned through contract tests and a staged cutover.
Five things worth carrying out of this part
- The gateway needs a model of the backend: an API is a named set of operations, each one verb at one path. The gateway models the shape, never the meaning.
- Import supported OpenAPI definitions from a reviewed file, inspect the result, then configure access and test against the backend. Reimport when the source changes.
- A named backend centralizes a service address and connection details for operations that use it. You can change that address without changing the public gateway URL; test routing and compatibility afterward.
- Mock responses let consumers integrate against the agreed contract before the backend exists — parallelising work that used to be sequential, because the contract, not the code, is the source of truth.
- Give consumers the gateway URL for this partner contract. Restrict direct backend access with network and authentication controls so gateway policy cannot be bypassed.
- Microsoft documents OpenAPI import restrictions, including definitions APIM ignores or supports only in part. Treat the imported model as something to inspect and test, not as automatic enforcement of the full file. ↩
- The mock-response policy can return an example, a schema-generated sample, or an empty body. It does not exercise the real backend's input-dependent behavior. ↩
Import an OpenAPI definition and shape the API the gateway exposes.
Play the lesson above to stamp this class.