A contract between two programs
You have used a thousand APIs today without seeing one. When your phone showed the weather, it did not scrape a website; it asked a weather service a precise question and got a precise answer back, in a format it knew in advance how to read. That agreement — you may ask me these questions, in this shape, and I will answer in that shape — is an API: an application programming interface, the front counter one program offers to another. The classic image is the restaurant. You never walk into the kitchen; you read a menu, tell a waiter "the salmon," and food arrives. The menu is the API: it lists what you may order and hides everything about how the kitchen works. You do not know the chef's name, the supplier, or the stove — and that ignorance is the point, because the kitchen can change all of it without changing your dinner.
Class Sixteen already told you the sentence this part unpacks: everything in Azure is an API. When you run az vm create, the CLI is a waiter carrying your order to the Azure Resource Manager API; the portal is a fancier waiter for the same kitchen. This part slows that down to the level a gateway operates at, because API Management reads requests for a living, and you cannot throttle, authenticate, or route a thing you cannot read. Get the language here and the remaining seven parts stop being portal clicks and become sentences you understand.
The menu hides the kitchen on purpose.
REST and the verbs — the web's own API style
Many web APIs use a resource style often called REST: a noun has an address, such as /products/42 for one product or /products for the collection. An HTTP method such as GET or DELETE says what kind of operation is requested. This common shape helps people and gateways understand the route. A gateway can also front non-REST APIs; the method and path are useful conventions, not a requirement for having a gateway.1
REST calls are stateless in a specific sense: the server must be able to understand each request without relying on a conversation stored for that client between requests. The service still stores products, orders and other resource data; stateless does not mean “the server remembers nothing.” A client may send a token or other needed context with each request. This makes requests easier to route to different backend instances.
| Verb | Means | Safe? | Idempotent? |
|---|---|---|---|
| GET | Request a representation; do not make it delete or charge | Yes | Yes |
| POST | Create a new resource, or trigger an action | No | No |
| PUT | Replace a resource wholesale at a known address | No | Yes |
| PATCH | Modify part of a resource | No | No |
| DELETE | Remove a resource | No | Yes |
Safe means a method is intended for reading rather than asking the server to change a resource. A GET may still create a log entry; it must not delete a product or charge a card. A GET response can be cached when its headers and access rules permit. Idempotent means repeating the same request has the same intended effect on server state as sending it once. PUT and DELETE have that defined meaning, but a real implementation must honor it. POST often creates something new on each call; payment and order APIs can make a POST retry safe with an idempotency key. Check the operation and its side effects before any automatic retry.2
Status codes — how the answer says how it went
An HTTP response begins with a three-digit status code. The first digit groups the result: 2xx success, 3xx redirection, 4xx a request the server will not fulfill as sent, and 5xx a server-side failure. The code points you toward the next check; it does not prove who caused the problem. Retry only when the operation is safe to repeat, the failure may be temporary, and any Retry-After advice is respected.
| Code | Name | What it tells the caller |
|---|---|---|
| 200 | OK | Success, with a body — the everyday GET reply |
| 201 | Created | A resource was created; check the Location header or response for its address |
| 204 | No Content | Success, nothing to return — a common DELETE reply |
| 400 | Bad Request | The request itself is malformed; fixing the server will not help |
| 401 | Unauthorized | Valid authentication credentials are missing for this resource |
| 403 | Forbidden | The server understood the request but refuses it |
| 404 | Not Found | No matching resource at that address |
| 409 | Conflict | The request fights the current state — a duplicate, a race |
| 429 | Too Many Requests | Too many requests; honor Retry-After when supplied |
| 500 | Server Error | The server encountered an error; inspect logs before a safe retry |
| 503 | Service Unavailable | The service is unavailable; retry later only if the operation is safe |
401 means the request lacks valid authentication credentials for that resource. 403 means the server understood the request but refuses to fulfill it; insufficient permission is common, but the code alone does not prove a credential was valid. 429 means too many requests, often because a configured gateway or backend limit was reached. Check the response and the policy that produced it before diagnosing the caller.
The request, the response, and the contract
Pull one request apart, because the gateway acts on each piece. A request has a method and a URL (the verb and the noun), a set of headers (metadata — who you are, what format you want, your subscription key), and often a body (the data itself, usually JSON). The response answers with a status code, its own headers, and its own body. When 38d rewrites a header, validates a token, or strips an internal field, it is reaching into exactly these slots.
The agreement about what those slots will contain — which operations exist, what each expects, what each returns — is the contract, and its written form is an OpenAPI specification (you will still hear the old name, Swagger). An OpenAPI document is a machine-readable menu: a YAML or JSON file listing every operation, its parameters, and its response shapes. It matters enormously to this track for one reason — APIM can import supported paths and operations from it, saving manual entry. Check the imported result: policies, authentication, backend access and any unsupported spec features still need configuration. The developer portal can display documentation based on the published API model.
- API contract
- The promise an API makes about its operations, inputs, and outputs — the shape callers may depend on. OpenAPI is that promise written down in a form both humans and tools can read; breaking it silently is the sin the whole back half of this track guards against.
You met this file already: Class Sixteen's REST APIs & ARM is where Azure's own contracts and the request/response model were introduced, and the /swagger/ endpoint in this site's own footer is an OpenAPI document for CAMPUX's API. This part is that lesson turned toward the consumer's side of the counter.
Play it through
Three minutes, two callers, one contract. Add a field and watch both keep working, then pick the change that ships next and watch the wrong ones break a caller downstream. It plays on its own and stops when it needs your hands.
This part carries no lab. There is no infrastructure to stand up yet — only the vocabulary a gateway reads, and the gateway itself does not exist until 38b. Play the lesson above instead; it rehearses the one discipline that matters before you touch APIM, adding to a contract without breaking a caller, at zero cost and zero risk.
One request, one status
A partner asks the catalogue for a product that was deleted last week: GET /products/9999. Before you read on, write down the status code you expect back and one sentence the response body should contain.
Check your prediction
404 Not Found, with a body that says which product id was not found. Not 200 with an empty body, which looks like success, and not 500, which blames the server for a perfectly normal question. A contract that fixes this answer in advance is what lets the partner write code against it.
When a gateway becomes useful
Now the bridge to the rest of the track. One API with one caller may need no separate gateway. When partners depend on it, the team must identify callers, control usage, publish the contract, plan version changes and prevent direct access to any backend route the gateway is meant to protect. APIM is one way to centralize those controls. Configure authentication and network restrictions explicitly; a subscription key can track access, but it is not strong proof of a person or application’s identity.
Some concerns are shared across APIs, such as token validation and usage limits. Others, such as whether a partner may see a particular customer’s order, belong in backend authorization. Part 38b puts the gateway on the wire; later parts configure and test the controls. Keep both layers visible when diagnosing a request.
The catalog was already an API
Before any gateway, Campux's storefront already talks to its own catalog service over HTTP: the website calls GET /products to list goods and GET /products/{id} for one item's detail and stock. Nobody called it an API, but it is one — resources with addresses, standard verbs, JSON bodies, and a 404 when an SKU is discontinued. The catalog team even has an OpenAPI file, half-forgotten, generated by their framework.
When the partner request lands, the temptation is to treat "expose the catalog to partners" as a new build. It is not: the API exists, the contract exists, the spec exists. What is missing is everything around the request — identifying each partner, limiting them, hiding the backend, versioning the contract for outsiders. That is the whole realisation this part is for: the API was never the hard part. The front desk is. And the forgotten OpenAPI file is about to become the most useful document Campux owns, because 38c imports it in one step.
Reading a failing integration in ninety seconds
A partner says the API is down and reports a 403. You know the server understood the request but refused it; you do not yet know whether a token was valid, a product subscription was missing, an IP rule blocked the call or a backend policy denied access. Ask for a timestamp and request or correlation ID, then inspect the gateway trace and backend logs. Compare with a known-working request. The status code narrows the search; evidence identifies the failing control.
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 — DELETE is defined as idempotent. Repeating the request to remove item 42 should leave the cart in the same state. That does not guarantee a successful second response or excuse side effects such as duplicate notifications in a faulty implementation. A POST to create an order, charge a card or send a message may repeat the action unless the API has a reliable idempotency key or equivalent protection. Before enabling retries in a client or gateway, check the endpoint’s behavior and the outcome of the first attempt.
403 — the server refuses this understood request. In the question, the caller has already authenticated, so missing authorization fits. A 401 indicates missing or invalid authentication credentials for the target resource. A 403 by itself does not establish who the caller is: a network or policy rule can also reject a request. A 404 may conceal a resource’s existence, while 400 describes a problem with the request. Use the code and the service’s policy evidence together.
Resource paths, stateless requests and safe GET behavior are the three intended REST properties in this question. A stateless request supplies the context needed to process it without a stored client conversation. GET is intended for reading, though logging may still occur and caching depends on response rules. Gateways can front RPC, GraphQL and other styles too; these REST conventions make common policy decisions easier to express, rather than making gateways possible in the first place.
# catalog API — design notes
1. GET /products and GET /products/{id} to read the
catalog and one item.
2. Use GET /products/{id}/delete to remove an item,
so it's easy to trigger from a browser link.
3. Return 201 with the new item's URL when a POST
creates a product.
4. Return 429 with a Retry-After header when a caller
exceeds their rate limit.
Line two — a destructive action hidden behind GET. GET is intended to be safe: callers and automated tools should be able to request it without causing a product deletion. The fix is to use a method such as DELETE /products/{id} and enforce authorization. The other lines are reasonable design choices: GET paths for the collection and item, a 201 response when POST creates an item, and 429 when a usage limit is reached. Include a Location header for the new item when appropriate, and honor Retry-After when supplied.
Start with the trade-off. An API can use POST for an action, including a complex read, but treating every request as POST gives clients and intermediaries less information about which calls are safe and repeatable. Ask what the team gains from that choice before standardizing it.
Explain the cost. A GET clearly signals a read and can use ordinary HTTP caching when allowed. A POST read needs explicit cache behavior and extra care with automatic retries. A gateway can still route or limit POST operations using paths, headers or bodies, but the team must configure those rules instead of relying on standard method semantics. A payment POST needs an idempotency design regardless of the gateway.
For this product catalog, use GET to read and DELETE to remove a resource. Use POST for creation, with an idempotency key if a client may retry the operation. Document the request and response in OpenAPI and test how clients behave when the network fails after the server has already acted.
Lead with the image, not the acronym. "An API is a menu. You order from it without ever entering the kitchen — you say what you want in a form the waiter understands, and food comes back. The restaurant can change chefs, suppliers, the whole kitchen, and your dinner is unaffected, because the menu is the only promise you rely on." A non-coder has now understood the single most important property: an API hides how, and exposes what. That they can follow it is the point — the interviewer is testing whether you understand it well enough to make it simple.
Then turn the menu into the contract. "The written contract — we call it OpenAPI — is the menu printed and signed. It lists every dish, what you have to say to order it, and what arrives. It matters because the moment someone outside my company builds their business on my menu, I can't quietly change it. If I remove a dish they order every morning, their kitchen fails, not mine — and they will not have found out until it breaks." That connects the abstraction to money and to other people's mornings, which is the register this bootcamp rewards.
Close on why the written form earns its keep. "Because it is written and machine-readable, tools can act on it: my gateway builds itself from it, my partners get generated documentation from it, and I can diff two versions to see whether a change breaks the promise before I ship it. The contract turns 'don't break the API' from a hope into something a computer can check." That final sentence tells the interviewer you see the contract not as paperwork but as the thing that makes the entire rest of API Management possible — which is exactly why this track starts here.
Five things worth carrying out of this part
- An API defines requests one program can make of another and the responses it can expect. A written contract lets callers build against that promise.
- REST commonly names resources by URL and uses HTTP methods. GET is intended for reading; PUT and DELETE are defined as idempotent; POST often changes state. Caching and retry safety also depend on headers and implementation.
- Status codes group outcomes. 401 means valid authentication is missing; 403 means a request was understood but refused; 429 means too many requests. Investigate the policy and logs before assigning blame.
- A request is a method, a URL, headers, and a body; the response is a status, headers, and a body. The gateway reads and can rewrite every one of those slots — every policy in 38d is a rule about one of them.
- The contract's written form is OpenAPI. It matters because tools act on it: the gateway imports it, partners get docs from it, and a diff can catch a breaking change before it ships.
- REST is the dominant style this part teaches, but not the only one a gateway fronts. GraphQL sends every call as one POST and moves the "which fields" question into the request body; gRPC uses HTTP/2 and binary payloads; older SOAP APIs wrap everything in XML envelopes. APIM can front all of them, but the caching, verb-routing, and retry reasoning here is cleanest on REST — which is why this track starts there. ↩
- "Idempotent" has a precise edge worth the footnote: PUT and DELETE are idempotent by the HTTP spec, but only if your backend implements them that way. A DELETE that returns 404 on the second call instead of 204 is still idempotent in state (the thing is gone) even though the status differs — and a POST can be made idempotent with a client-supplied idempotency key, which is how payment APIs make retries safe. Treat the table as the default, not a law of physics. ↩
Explain what an API is, what REST promises, and why a gateway exists at all.
Play the lesson above to stamp this class.