The design module ended with a list of open questions, and the first one was the most concrete: exactly how do the services talk to each other. We have decided that POST /orders responds 202 Accepted, that Orders looks up the catalog with GET /products?ids=, that Inventory exposes POST /reservations; but a contract is not a route name: it is the exact shape of the request, the response, the status codes, the error format and the headers that both sides commit to honoring. This lesson turns those design decisions into complete REST contracts.

REST is the synchronous communication style TechCorp will use in two places: in the public API (what the web and the mobile app consume through the gateway on port 8080) and in the few internal synchronous calls that 02-02 left authorized (Orders → Catalog and Orders → Customers). We will look at how resources and URIs are modeled, the semantics of the verbs and their idempotency, the status codes we will use throughout the course, TechCorp's five key contracts with request and response examples, a uniform error format based on RFC 7807, pagination, filtering, HATEOAS at a practical level, useful headers, documentation with OpenAPI 3 and, finally, a minimal Express endpoint and a fetch client that apply the contract. Versioning is left for 03-06, the gateway for 03-04 and resilience (retries, circuit breakers) for 06-03: here only the timeout appears, as the minimum good practice.

1. REST in microservices: what it is and what it is not
2. Resources and URIs
3. HTTP verbs, semantics and idempotency
4. The status codes we will use
5. TechCorp's key REST contracts
6. Uniform error format: RFC 7807
7. Pagination, filtering and sorting
8. HATEOAS at a practical level
9. Useful headers
10. Documentation with OpenAPI 3
11. An Express endpoint and a fetch client that apply the contract

REST (Representational State Transfer) is neither a protocol nor a library: it is a set of design constraints on top of HTTP. The ones that matter to us in microservices are four:

• Resources identified by URIs. An order is /orders/ord-88213; a product, /products/p-501. The URI identifies the thing, not the action.
• Manipulation through representations. The client never touches the PostgreSQL row: it sends and receives representations (JSON) of the resource.
• Uniform interface. The HTTP verbs (GET, POST, PUT, PATCH, DELETE) mean the same thing in every service. Nobody invents POST /orders/get.
• Stateless between requests. Every request carries everything it needs (authentication, identifiers). This is what lets us run eight replicas of Catalog behind a load balancer (03-05) without caring which one answers.

What REST is not: it is not "anything that returns JSON over HTTP". The difference between a REST API and an "RPC over HTTP" API lies in the use of the uniform interface, and in microservices it matters because the REST contract is the only boundary between teams: if the Orders team (Luis) can guess how a Catalog endpoint behaves just by reading its URI and its verb, there are fewer meetings, less documentation and fewer surprises.

TechCorp's rules for naming URIs, aligned with the principle from 02-01 that "contracts express business":

One case that causes confusion: actions that do not fit a verb. How do you cancel an order? There are two respectable options:

• Treat the cancellation as a state change: PATCH /orders/ord-88213 with {"status": "CANCELLED"}. Simple, but it mixes very different changes into a single endpoint.
• Model the action as a sub-resource: POST /orders/ord-88213/cancellation. It creates "a cancellation" of the order, with its own body (reason) and its own validation. This is the one TechCorp will use, because the saga from 02-05 treats the cancellation as a business fact with a reason, not as a field edit.

What we will never do is POST /orders/ord-88213/cancel with the verb in the URI, or expose the internal structure: /orders/ord-88213/lines yes, /order_lines?order_id= no.

Each verb has a meaning and two properties that are critical in distributed systems: whether it is safe (does not modify state) and whether it is idempotent (repeating it N times has the same effect as doing it once).

Why idempotency matters: in 01-02 we saw that the network is not reliable. If Orders calls PUT /customers/c-1024/address and the response gets lost, it can repeat the call without fear: the address will end up the same. If it repeats a POST /reservations that was already processed, there will be two reservations and the stock of p-501 will drop twice. That is why, in 02-05, we introduced the Idempotency-Key header for POST /orders: it makes a POST repeatable without changing its semantics. We will apply it to POST /reservations as well.

About PATCH: {"price": 54.90} is idempotent (repeating it leaves the same price); {"incrementStock": 5} is not. TechCorp's rule: PATCH bodies describe the desired state, never deltas.

There is no need to memorize the ~60 HTTP codes. TechCorp uses a closed subset, and every service applies it the same way (we will package it in @techcorp/common-http, the technical library from 02-02):

Two nuances that TechCorp fixes by convention so that every team responds the same way:

• 400 versus 422. 400 is "I don't understand your request" (it is not JSON, a field is missing, a number arrives as text). 422 is "I understand it but it makes no sense" (quantity 0, delivery date in the past). The distinction helps the client know whether the error is about serialization or about business.
• 404 versus 409 in business errors. From the monolith we inherited four errors: CUSTOMER_NOT_FOUND → 404, PRODUCT_UNAVAILABLE → 400, OUT_OF_STOCK → 409, PAYMENT_REJECTED → 402. In the new architecture POST /orders responds 202 before knowing whether there is stock or whether the payment goes through, so OUT_OF_STOCK and PAYMENT_REJECTED stop being HTTP responses of that endpoint and become reasons of order.cancelled. OUT_OF_STOCK is still a 409 from POST /reservations (Inventory). PRODUCT_UNAVAILABLE becomes 422 (the request is well-formed, but asks for something that is not on sale).

This is the most important contract in the course. Request: the client sends only what it knows: what it wants and where to send it. It does not send product names or prices (Orders freezes them by querying Catalog, as the aggregate from 02-03 establishes), nor the total (Orders computes it).

Response: 202 Accepted because, as we decided in 02-05, the saga (stock reservation, charge, confirmation) is still in progress. Location says where to check the progress. The body returns the order as it was saved, with the prices already frozen and the status PENDING.

Behavior with Idempotency-Key: if the same client repeats the request with the same key (because it lost the response), Orders looks up idempotency_keys (02-05) and returns exactly the same response, without creating another order. If the key is reused with a different body, it responds 422 with code IDEMPOTENCY_KEY_REUSED.

Possible errors from this endpoint (all in the format of section 6):

This is the read that follows the 202: the web polls (or receives a notification) until the status is no longer PENDING.

If the order has not changed since version "v3", the server responds 304 Not Modified without a body (it saves bandwidth during polling). If the order belongs to another customer, 403; if it does not exist, 404.

This is the most frequent internal synchronous call: Orders needs the name, price and availability of each line in order to freeze them. Designing GET /products/{id} and calling it once per line would be the classic N+1 problem: an order with 20 lines would mean 20 network round trips. That is why the contract accepts a batch:

Contract decisions worth explaining:

• Ids that do not exist do not cause a 404. A batch is a query against the collection; one missing id does not make the request fail. They are returned in notFound and it is Orders that decides what to do (respond 422 PRODUCT_UNAVAILABLE).
• Batch limit. At most 100 ids; above that, 400. Without a limit, someone would end up requesting 5,000 products in a URL.
• Cache-Control: max-age=30. The catalog changes little; allowing 30 s of client-side caching reduces load during the ×20 peaks.
• This JSON is the published language from 02-03; Orders translates it with its productTranslator into its own model, so that if Catalog changes price (we will see it in 03-06), only the translator changes.

Orders usually resolves the customer from its local replica customers_ref (02-04), but when the replica does not have it yet (a freshly registered customer) it makes this call:

Note what it does not return: password, tokens, payment details. The representation is a business view of the customer, not a dump of the table.

In the choreography saga from 02-05, Inventory reserves stock by reacting to the order.created event, not through an HTTP call. Why a POST /reservations then? For three reasons: for the internal admin panel, for testing, and because in 02-03 we left open a partnership relationship Orders↔Inventory that in the future could become synchronous (gRPC in 03-03). Designing the contract now costs little and fixes the vocabulary.

Response when there is stock. Here it is 201, because the reservation is made at that very instant (a local transaction in Inventory's database):

And when there is no stock, a 409 detailing what is missing (information the saga turns into stock.rejected):

Using orderId as the Idempotency-Key is deliberate: "one reservation per order" is exactly the guarantee we want.

In the monolith, each controller returned errors however it saw fit: sometimes {"error": "..."}, sometimes {"message": "..."}, sometimes HTML. With six services and four teams, that multiplies. RFC 7807 (Problem Details for HTTP APIs) defines a standard format with the MIME type application/problem+json:

The code field is the extension TechCorp standardizes: a stable identifier in UPPER_SNAKE_CASE (CUSTOMER_NOT_FOUND, OUT_OF_STOCK, PRODUCT_UNAVAILABLE, INVALID_REQUEST, INVALID_DATA, DEPENDENCY_UNAVAILABLE, STALE_VERSION, IDEMPOTENCY_KEY_REUSED). Clients switch on code, never on detail, which is text for humans and may change.

Example of a validation error with per-field detail (errors extension):

Mapping of the errors inherited from the monolith to the new model:

A security tip: on a 500, detail never includes the exception message or the stack trace (it would leak paths, SQL queries, host names). It is logged with the X-Request-Id and the client receives a generic detail with that identifier so it can report it.

Every collection that can grow is paginated; GET /orders without a limit would end up returning 3,000 daily orders accumulated over years.

Cursor-paginated response. The cursor is an opaque string (usually base64 of the {createdAt, id} of the last element) that the client sends back as is:

TechCorp's conventions for filtering and sorting:

• Filters as query parameters named after the field: ?status=CONFIRMED, ?customerId=c-1024. Ranges with suffixes: ?createdFrom=2026-08-01&createdTo=2026-08-15.
• Sorting with sort=field ascending and sort=-field descending; multiple fields separated by commas: sort=-createdAt,id.
• limit with a default value (20) and a maximum (100). A client asking for 10,000 gets 400.
• Only filters and sort orders documented in OpenAPI are supported; an unknown parameter is ignored (tolerance, which 03-06 will formalize), but an invalid value in a known one yields 400.

HATEOAS (Hypermedia As The Engine Of Application State) is the REST constraint that says the response must include links to the possible actions, so that the client "navigates" the API instead of building URIs. Taken to the extreme it produces APIs that are hard to consume, and few people apply it fully. TechCorp adopts a pragmatic version:

• A _links object with self, always.
• Links to actions that depend on the state: a PENDING order includes cancel; a CONFIRMED one includes invoice but not cancel. This way the front end does not duplicate the state machine from 02-05 to know which button to show.
• Pagination links (next, prev).
• Nothing else. Resources from other services are not linked (an order does not link to Customers' /customers/{id}), because the client always enters through the gateway and internal URIs are of no use to it.

Optimistic concurrency example: two administrators edit the price of p-501 at the same time.

If the product is already at version 13 because the other administrator saved first, Catalog responds 409 with code: STALE_VERSION and the client reloads and decides. Without If-Match, the second save would silently overwrite the first.

A contract that only lives in Luis's head is not a contract. OpenAPI 3 is the standard specification (YAML or JSON) for describing REST APIs: routes, parameters, bodies, responses and schemas. From it you generate browsable documentation (Swagger UI, Redoc), clients, request validators and, in 04-05, tests. Fragment of the Orders and Catalog specification:

And the Catalog batch, in its own document (each service publishes its own OpenAPI; there is no global file):

How to read it: paths groups routes; within each verb, parameters describes query/headers/path, requestBody the body, and responses each code with its schema. components avoids repeating schemas and responses. In 03-06 we will see that writing this YAML before the code (design-first) is how Orders and Catalog get to work in parallel.

We are not building the full service yet (structure, configuration and startup belong to module 4); only the piece that materializes the POST /orders contract.

Step-by-step explanation:

1. validateNewOrder separates the two levels: if the shape is wrong it returns 400; if the shape is fine but the values are not, 422 with the list of fields. It is exactly the distinction from section 4.
2. sendProblem centralizes the RFC 7807 format. In the real project this function lives in @techcorp/common-http so that Catalog, Inventory and the rest respond identically.
3. The route checks Idempotency-Key, validates, delegates to the use case (which we already know from 02-05: it saves the order and its order.created in the same transaction with saveWithEvents()), and responds 202 with Location. Notice that the route knows nothing about RabbitMQ or stock: it only translates HTTP into business and business into HTTP.
4. Business errors are mapped to contract codes; anything else goes to Express's error middleware, which responds 500 without leaking details.

And the client: how Orders calls the Catalog batch. Node.js 20 includes fetch natively, and AbortSignal.timeout is the minimal way not to wait forever.

Key points of the client: the base URL comes from configuration (CATALOG_URL, whose default value is the stable service name we will justify in 03-05 and manage in 04-03); X-Request-Id is propagated; there is a 2 s timeout (without it, a Catalog outage would exhaust Orders' connections); "did not respond" is distinguished from "responded with an error"; and notFound is translated into the business error of the POST /orders contract. What is not here (retries, circuit breaker, fallback) is the subject of 06-03.

• Verbs in URIs (/orders/create, /products/search). If you catch yourself writing a verb, ask what the resource is: it is almost always a collection (POST /orders) or a sub-resource (POST /orders/{id}/cancellation).
• Returning 200 for everything and putting the error in the body ({"ok": false}). It breaks HTTP caching, the gateway's monitors and every client's intuition. Use the table from section 4.
• 201 when the work is not done. If at response time you still do not know whether there will be stock, it is 202. A 201 promises that the resource is complete.
• N+1 out of convenience. GET /products/{id} in a loop looks clean until a 15-line order takes 15 × 40 ms. Design batches (?ids=) from the start.
• Idempotency-Key without persistence. Storing keys in process memory does not work with two replicas: the idempotency_keys table from 02-05 is mandatory.
• Error messages as the contract. Clients must look at code, not detail. Changing a text should not break anyone.
• Leaking internals in 500 errors. Never detail: err.stack. Full log with X-Request-Id; to the client, a generic message with that id.
• Forgetting the timeout in the client. fetch without signal waits indefinitely. Two seconds for internal calls is a good starting point.
• Documenting afterwards. An OpenAPI written after the fact goes stale. Write it first (03-06) and validate requests against it.

Exercise 1. Design the REST contract for "cancel an order" for the Orders service: URI and verb, request body (with reason), success and error responses with their status codes and code, taking into account the state machine from 02-05 (cancellation is only possible in PENDING, STOCK_RESERVED or PAID; not in CONFIRMED nor if it is already CANCELLED). Write an http example of a request and of an error response.

Exercise 2. The Shopping Experience team proposes GET /customers/c-1024/orders (in the Customers service) so that the web can show a customer's order history. Reason about whether that endpoint should live in Customers or in Orders, which URI you would propose, and which pagination strategy (offset or cursor) you would choose and why. Write the JSON response of the first page with two orders.

Exercise 3. Write an Express patch('/products/:id') function for Catalog that applies optimistic concurrency with If-Match. Assume there is a repository.get(id) that returns { ...product, version } and a repository.updateIfVersion(id, changes, expectedVersion) that returns the updated product or null if the version does not match. Respond 428 Precondition Required if If-Match is missing, 404 if it does not exist, 409 STALE_VERSION if the version does not match and 200 with a new ETag if it succeeds.

Solution 1.

Contract: POST /orders/{id}/cancellation. The cancellation is a business fact with its own data (reason, who cancels), not the edit of a field, and POST is the verb for "create a sub-resource". It should accept Idempotency-Key (or, more simply, be idempotent by design: cancelling an already-cancelled order for the same reason returns 200 with the same body).

Responses:

One could argue for 200 instead of 202 if the order is considered CANCELLED synchronously and the compensations are an internal detail; both are defensible, but the chosen one must be documented in OpenAPI and applied the same way across the whole API.

Solution 2.

Orders belong to the Orders bounded context (02-03): the history must be served by the Orders service, which owns the data and its up-to-date status. Putting the endpoint in Customers would force Customers to query Orders (unnecessary coupling) or to replicate orders (which do not belong to it). Proposed URI: GET /orders?customerId=c-1024&sort=-createdAt&limit=20 in Orders. The nested route /customers/{id}/orders can be offered by the gateway or the BFF (03-04) as a convenience for the front end, redirecting it internally to Orders, but the canonical contract is the filter on the /orders collection.

Pagination: cursor. A customer's history grows at one end (new orders come in at the top), it is a potentially large collection and the use case is "infinite scroll" on the web and in the app, not "go to page 7". With offset, a new order created while the user browses would shift everything and repeat an element between pages.

Solution 3.

Points to check: the response ETag reflects the new version (13), so that a second PATCH from the same client can chain; and updateIfVersion must perform the check in the same SQL statement (UPDATE ... WHERE id = $1 AND version = $2), not in two steps, for the optimistic concurrency to be real.

We have turned the design decisions from module 2 into concrete REST contracts: URIs with nouns and hierarchies, verbs with their idempotency (and Idempotency-Key when the verb lacks it), a closed table of status codes that every service applies the same way, TechCorp's five key contracts (POST /orders with 202 + Location, GET /orders/{id} with ETag, GET /products?ids= in batch to avoid the N+1, GET /customers/{id}, POST /reservations with 201/409), uniform RFC 7807 errors with the code field replacing the monolith's scattered errors, cursor pagination for growing collections, minimal HATEOAS, caching, optimistic concurrency and correlation headers, OpenAPI 3 as the written form of the contract, and an Express route and a fetch client with timeout that apply it.

REST covers the synchronous calls, but in 02-05 we decided that the heart of the order flow (reserving stock, charging, confirming, notifying) travels through events: order.created, stock.reserved, payment.confirmed, order.confirmed, order.cancelled. We still need to see how they are really published and consumed: what an exchange and a queue are in RabbitMQ, how each event is routed to whoever is interested, what happens when a consumer fails and how we guarantee that an event is neither lost nor processed twice. That is asynchronous messaging, the next lesson.