MAIE6000C Chap.5 APIs and Network Communication
APIs and Network Communication
Interfaces are where assumptions become checkable
The published topics for this week are interface design in the representational style, request and response contracts, validation, error handling, service boundaries, idempotency, and the fundamentals of authentication and authorisation.
The module explains why those belong together: interfaces are where engineering assumptions become concrete, and good design creates clarity around data flow, error behaviour, service boundaries and responsibilities across the system.
Three kinds of endpoint, three different promises
The starter's own set sorts cleanly. Operational probes answer about the process and do not touch user data.
Reads return current state and are safe to repeat. One create changes state and returns a new case together with the job that will process it.
The distinction is load-bearing rather than tidy: it decides which calls a client may retry freely, which need a key to make repetition safe, and which a monitoring system may poll without side effects.
Validation belongs to the boundary
Each crossing validates what it cannot assume about the other side. An external caller can send anything, so the shape, the types, the ranges and the size are all in question.
Another team's service owes at least a shape and a contract version. Your own worker reading your own store is in a different position but not a trusting one, because the store may hold rows written by an earlier schema.
Inside a module, validating types you constructed yourself is noise that hides the checks that matter.
Liveness and readiness fail in opposite directions
Liveness asks whether the process is alive and must answer without depending on anything else, or an outage elsewhere will cause a healthy service to be restarted for a fault it cannot fix.
Readiness asks whether the service can serve real requests, which normally means its dependencies are reachable, and it is allowed to report failure while the process stays up. The starter exposes both and each payload names the service that replied, which is the detail that makes them useful when four containers answer at once.
Idempotency is a property of the contract
Retries are not hypothetical.
A slow connection, a user pressing submit twice, a worker restarting mid-call and a timeout firing after the server already committed all produce the same request arriving more than once. The repair is never to ask callers to behave. It is to let the caller name the request with a key, to write that key together with the created records in one transaction, and to return the same answer on the repeat.
Reads have this property for free, which is why sorting endpoints by kind comes first.
Error behaviour is part of what you are graded on
The proposal rubric scores interface and asynchronous workflow design together, and its top band describes a coherent boundary design with a clearly identified worker path. Coherent includes what happens when things go wrong.
Decide which failures are the caller's and which are yours, because that determines whether a caller should retry. A response indistinguishable from a transient failure invites a retry storm, and one that looks transient but is permanent produces a client that never stops trying.
What this chapter covers
- 01
Three kinds of endpoint and the promise each one makes
- 02
The four decisions a contract has to settle, including the two teams skip
- 03
How much validation a crossing owes, by who is on the other side
- 04
Internal against external interfaces, and why the distinction costs money
- 05
Liveness and readiness as two questions with opposite failure modes
- 06
Idempotency keys, and why the write has to be one transaction
- 07
Whose fault a failure is, and whether the caller should retry
- 08
Authentication and authorisation as two separate questions
Make a create endpoint safe to repeat
- 3State the mechanism that lets the service recognise a repeat.
- 3Say what must be written together, and why.
- 2Say what the repeated call must return.
Key terms
- Request Contract
- The agreed shape of what a caller sends and what comes back, including the responses for malformed input and for a dependency being unavailable.
- Service Boundary
- The line across which one component calls another, which determines how much validation is owed and how stable the interface has to be.
- Idempotency Key
- A caller-supplied identifier for a request, stored with the records it created so that a repeat returns the original answer instead of creating more.
- Liveness Probe
- An endpoint reporting whether the process itself is running, deliberately independent of dependencies so that an outage elsewhere does not trigger a restart.
- Readiness Probe
- An endpoint reporting whether the service can serve real traffic, normally by checking that its dependencies are reachable.
- Authorisation
- The question of whether a known identity is permitted to perform an action, distinct from authentication, which only establishes who is asking.
- Transient Failure
- A failure that may succeed if repeated, which is why a response has to say whether retrying is worthwhile rather than leaving the caller to guess.
APIs and Network Communication FAQ
What is the difference between a liveness and a readiness check?
They answer different questions and they fail in opposite directions. Liveness asks whether the process is alive and should depend on nothing else, because a probe that queries the database will report unhealthy during a database outage and cause the process to be restarted for a fault it did not have.
Readiness asks whether the service can handle real requests, which usually means its dependencies are reachable, and it is allowed to report not ready while the process stays up. The starter exposes both, and both payloads name which service answered, which matters when four containers are responding.
Why does my submit endpoint need an idempotency key?
Because the same request will arrive twice whether or not you plan for it: a user presses submit again on a slow connection, a timeout fires after the server has already committed, a client library retries automatically. Without a key the service cannot tell a repeat from a genuinely new item, so it creates a duplicate item, a duplicate job and a duplicate result.
With one, the second arrival returns the first arrival's identifiers and creates nothing. The two details that decide whether it works are writing the key in the same transaction as the records, and returning the same response rather than merely a harmless one.
What should an endpoint return when a dependency is down?
Usually acceptance, not rejection. If the submitted item is valid, the correct behaviour is to store it, create the job and let the job sit queued until the background service returns. That is the whole argument for having a queue: acceptance should not depend on the slow component being available.
What the response owes the caller is the distinction between this case and a malformed request, because one is worth retrying identically and the other is not. Deciding which failures are the caller's and which are yours is part of the contract the proposal rubric scores.
Assessment move
For each endpoint you have, write down on one line what it accepts, what it returns on success, what it returns on bad input, and what it returns when a dependency is unavailable. Most teams can complete the first two columns immediately and stall on the fourth, and the stall is the finding: that is the case your midterm demonstration cannot currently show.
Working through APIs and Network Communication in MAIE6000C? Sia is AskSia’s AI Computer Science tutor — ask any MAIE6000C APIs and Network Communication question and get a clear, step-by-step explanation grounded in how MAIE6000C is taught and assessed. Read this chapter free, then take your hardest questions to Sia.
