Read API contracts, preserve complete evidence collections, and distinguish signed credentials from secret data.
50 min 135 XPSkills: API contracts, Reliable collection, Token safety
Brief
At Halcyon Clinics, an overnight collector reports 100 access reviews as the entire quarterly population. There are actually 243. A developer retries a timed-out creation request and produces duplicate reviews; an analyst then pastes a signed token into an evidence note, calling it encrypted. Each mistake crosses a different API boundary.
You will follow a request from its resource and method through structured data validation, retries, collection and authentication. The aim is not just a successful HTTP response: it is a complete, reproducible evidence set without duplicate changes or disclosed credentials. An API contract must specify what a client sends, what the server guarantees, and what happens when either side fails.
A 200 response proves one request succeeded; it does not prove the evidence population is complete.
Resources, methods and repeatable effects
REST models resources with identifiers: /reviews is a collection, while /reviews/42 identifies one review. GET reads without requesting a state change; POST commonly creates a collection member and returns 201 with a Location header. PUT replaces the representation at a known identifier; PATCH applies a partial update. DELETE requests removal. A method name does not enforce authorization: the server must check the caller's permission on the specific review, not just possession of a credential.
Idempotent means repeated identical requests have the same intended server effect as one request, not identical response bytes. GET, PUT and DELETE have idempotent semantics; a second DELETE may return 404 instead of 204. POST is not inherently idempotent, and PATCH depends on the operation: setting a flag differs from incrementing a counter. For POST /reviews, an Idempotency-Key can make retries safe when the server atomically binds the key to the caller, operation and request fingerprint, retains the original result, and rejects a changed payload under that key. Reuse the key only for retries of one logical operation within the documented retention window.
For change-integrity controls, retain request identifiers, authorized actor, resource identifier, outcome and a safe correlation reference, not full credentials. Test a timeout followed by a retry and verify that only one record exists. An auditor can ask whether duplicate suppression is actually enforced server-side rather than merely suggested by a header.
JSON and YAML need a contract
JSON represents objects, arrays, strings, numbers, booleans and null. For example, {"id":"0042","approved":false,"count":3} preserves the identifier as text and the decision as a boolean. JSON requires double-quoted property names and strings; comments and trailing commas are not valid. Parsing succeeds even if "approved" is the string "false", so valid syntax alone does not establish a valid decision.
YAML uses indentation for mappings and sequences: a dash introduces a list item, and spaces establish nesting. Quote identifiers such as "0042" and date-like values when they must remain strings; scalar resolution varies between parser versions. Use safe data-only loading for untrusted YAML, reject duplicate keys, and bound input size and nesting. YAML is convenient for authored configuration, while JSON is common for API bodies; neither format itself supplies authorization or semantic validation.
A schema adds required fields, types, enums and bounds. A review schema might require id as a string, approved as a boolean, and count as an integer with minimum zero, while rejecting unknown properties. A request with approved: "false" must fail rather than be coerced into a truthy string. Retain schema versions and negative test results as input-validation evidence; ask which version validated each batch and whether malformed records were quarantined instead of silently discarded.
Pagination and backpressure preserve the population
A collection endpoint may return items plus next_cursor. With a page limit of 100, a 243-record snapshot requires three pages containing 100, 100 and 43 items. Follow the returned cursor until the documented terminal value, such as null; do not infer completion from a short page unless the contract guarantees it. Offset pagination can skip or duplicate records as rows change. A stable snapshot and ordering, cursor progress checks, and deduplication by immutable record identifier make an evidence export more defensible.
HTTP 429 means the caller exceeded a rate policy, not that the next page is empty or authentication failed. Retry-After can be delay-seconds or an HTTP date. Respect it, then retry the same pending cursor; otherwise use bounded exponential backoff with jitter under the published policy. Cap attempts and elapsed time, checkpoint progress and mark an exhausted run incomplete. A 429 must never advance the cursor or turn an incomplete collection into a successful audit report.
Population-completeness evidence includes the snapshot or query window, page counts, unique record count, terminal cursor state and retry history. Reconcile those counts with an independent source total where available; deduplication cannot recover missing records. An auditor asking why 243 records were expected needs more than three successful status codes.
Retry the pending page without confusing throttling with the end of a collection.
Credentials, bearer semantics and readable JWTs
An API key commonly identifies an application or integration, often as a long-lived opaque secret; it does not automatically identify a human or provide fine-grained permissions. A bearer token grants whoever holds it the authority associated with that token. Tokens may be opaque or structured, and API keys can also behave as bearer credentials. Prefer explicit scopes, bounded lifetimes, rotation and revocation, TLS in transit, and secret storage; placing either credential in a URL risks disclosure through histories and logs.
A signed JWT in compact form has three base64url-encoded segments: header.payload.signature. The header describes metadata such as the signing algorithm and key identifier; the payload contains claims such as issuer, subject, audience and expiration. The signature or message authentication code protects integrity when correctly verified; base64url is encoding, not encryption. Anyone holding this signed token can decode its payload without a signing key. Encrypted token formats exist, but three-part signed JWT structure is not one of them.
Never trust claims merely because decoding succeeded. Restrict allowed algorithms and trusted keys, verify the signature, then validate issuer, audience, expiration and any not-before time with a small documented clock tolerance. Still enforce resource-level authorization. For access-control assurance, collect redacted validation outcomes and expiry or revocation tests, not raw tokens. An auditor should be able to distinguish a correctly rejected wrong-audience token from a token whose readable claims were simply trusted.
Readable claims become trustworthy only after cryptographic and contextual validation.
Tasks
Answers are graded on the server: the answer key never reaches your browser.
Task 1: The harmless retry
Scenario sim+45 XP
Read the brief and answer both questions.
Incident brief
A POST to /reviews times out after the server commits the new record. The operations lead says POST is inherently safe to repeat and proposes a fresh request key on every retry. The documented endpoint instead caches the result for one logical operation when its original deduplication header is reused.
A separate client must replace the complete representation at the already-known resource /reviews/42, not create a collection member or partially patch it.
Term bank, not all of these are right
Idempotency-KeyPUTPOSTRetry-After
1.1Which request header should remain unchanged across retries of the timed-out logical creation? (one hyphenated term)
1.2Which HTTP method expresses replacement at the known resource identifier? (one word)
Task 2: One green page
Scenario sim+45 XP
Read the brief and answer both questions.
Incident brief
The export contract returns at most 100 items per page and ends only when next_cursor is null. An analyst labels the first 100 records a full population because the response is 200. The next request returns 429 and Retry-After: 20; a colleague calls that an authentication failure and proposes ending the run.
Term bank, not all of these are right
pagination20authentication100
2.1Which collection mechanism must the client continue to obtain the remaining records? (one word)
2.2How many seconds does this response require the client to wait before retrying the pending page? (a number)
Task 3: Readable is not trusted
Scenario sim+45 XP
Read the brief and answer both questions.
Incident brief
An engineer decodes a three-part signed JWT and sees a patient identifier. The engineer calls this a broken encryption implementation, then suggests accepting any token whose decoded payload says role=auditor. Separately, the import accepts {"approved":"false"} because it is valid JSON, despite the contract requiring a boolean.
Term bank, not all of these are right
signatureschemaencryptionpagination
3.1Which third JWT segment must be cryptographically verified before trusting claims? (one word)
3.2Which data contract defines required properties and types beyond JSON syntax? (one word)
Labs
80 bonus XP
Hands-on work. You edit the artefact, the server runs the checks: the expectations and the reference solution never reach your browser.
Halcyon Clinics needs a read-only review export. The draft collector treats throttling as end-of-data and calls string-valued decisions acceptable because they parse. Its author also proposes putting the credential in the query string so troubleshooting is easier.
Write the YAML plan using the fixture contract. Fill every empty scalar, use actual YAML booleans for flags, and preserve incomplete-run failures. This plan specifies behavior; it does not contain a live secret.
Export contract and acceptance requirements
Resource: /reviews; read-only collection method required.
Response media type: application/json.
Schema: approved is required and boolean; reject invalid records.
Paging: next_cursor; stop only at null; snapshot contains 243 records.
Throttle: HTTP 429, Retry-After: 20; retry the pending page after the delay.
On exhausted retries: mark the run incomplete.
Credential: bearer token in Authorization header, never query parameters.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
Checks
Read the specified JSON collection
Reject non-boolean decisions
Follow cursors and reconcile the population
Respect the throttle and preserve the pending page
Fail closed on exhausted retries
Keep bearer credentials in the authorization header
The integration owner marks all six design claims approved because the endpoint returns JSON over TLS. Review each claim independently; transport encryption does not repair incorrect application semantics.
Reject only claims contradicted by the stated behavior. Use one root-cause code per rejection and leave accepted reasons empty. The codes mean: duplicate-effect for unsafe logical retries; type-confusion for missing semantic type checks; incomplete-export for stopping before completion; token-confidentiality for treating signed claims as secret.
Verdicts are accept or reject. Every rejection needs one reason code from: duplicate-effect | type-confusion | incomplete-export | token-confidentiality.
Design claims awaiting approval
AP-1: POST creation timed out; retry with a fresh idempotency key to ensure the original operation is not duplicated.
AP-2: Require approved to be boolean; reject the string "false" even though the JSON parses.
AP-3: A 429 is equivalent to next_cursor null, so publish the current export as complete.
AP-4: The three-part signed JWT payload can safely contain secrets because its signature encrypts it.
AP-5: Verify the token signature using trusted keys and allowed algorithms, validate issuer, audience and time claims, then authorize the resource operation.
AP-6: JSON syntax validation alone proves approved has the boolean type required by the contract.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
Checks
Every line in the fixture carries a verdict
Accept and reject land on the right lines
Each rejection cites a valid reason code
Next on your path · Application Fundamentals
Databases for Applications
Trace application data through keys, queries and transactions, then defend database access, recovery and audit evidence.
