AI disclosure: Drafted with AI assistance for Apiary. All routes and examples are fictional. This article describes a proposed test, not observations from a deployed service.
At a fictional public reading room, a visitor follows a link to an exhibit card and reads it in a browser. A volunteer's command line tool follows exactly the same URL and obtains the card as JSON. Both interactions can return status 200 and still fail. The browser could display a block of serialized fields instead of the expected document. The tool might hold an HTML error page presented as a successful response. Even if both work in isolation, an intermediary that remembers only the URL might return whichever version was requested first. The trouble is not the route itself. The route identifies the right resource. The trouble is that two different consumers ask for two different ways to represent it.
To understand a contract like this, start with a four sentence specification and a small fixture. Define what makes the representations equivalent, what means they are different, what clients may request, and what happens when none of the supported choices is acceptable. Then make the examples small enough for a person to check without launching a full application. A fixture won't tell you how an unspecified hosting platform behaves. It can tell you whether the application emits the instructions that make two independent representations possible, and whether a deliberately limited stand-in obeys the instructions you wrote down.
Decide what the fixture represents
Give the example a printable name and a stable identifier. Consider the invented Lantern Label, identifier exhibit-07. It has one title, one public room, and one sentence about an imaginary brass lantern. None of these details need a database. The HTML page has a document title, main heading, and prose. The JSON has an object with an explicit identifier, title, room, and sentence. Both describe exhibit-07. Their bytes, presentation, and schema are intentionally different. Putting the identifier in both allows a test to prove it asked about the same thing instead of comparing two unrelated pages.
Use distinct, minimal bodies. A hundred lines of generated HTML introduce moving pieces that obscure the teaching point. A representation test can check a parsed heading and an explicit identifier, not the order of every attribute in a page template. For JSON, assert a parsed object, the intended fields, and meaningful values. Do not merely assert that the body contains the word lantern. A template rendering the JSON in a preformatted block would pass that check, but would not be the intended document. A defensive test should fail when the advertised content type, parsed format, or underlying entity is wrong.
A request can have a body of its own, but this example doesn't need one. The client preference is an Accept request header. The server's answer advertises the returned media type in Content-Type. They are related but not interchangeable. An ordinary GET with no body can ask to receive JSON. Setting a request Content-Type without an Accept header does not express that response preference. One useful negative case sends no Accept header and attaches a request Content-Type in a harness where that is representable. The response should follow the documented default rather than being accidentally steered by the irrelevant header.
There is no requirement to have one URL serve both formats unless that is the product contract. Separate document and data URLs can reduce variation, make receipts easier to search, and avoid some accidental dependencies on client defaults. If the resource already supports multiple representations at one URL, product compatibility may be a better reason to test than a preference for tidiness. In either design, the fixture should encode the behavior that a client can reasonably depend on, not the handling that happens to emerge when the dev server boots.
Start the contract with a public fact, not a serializer
The strongest comparison begins by naming the facts shared by the intended audiences. Both renderings of the fictional object card identify exhibit-07 and should describe the same lantern in the same public room. The page can contain a paragraph of welcoming context, while the data feed omits navigation markup because it is intended to supply an inventory. Neither representation has to duplicate irrelevant decoration. But if the room field and the visible exhibit heading lead different people to different rooms, the application hasn't merely introduced a typography change. It has changed a fact about the resource.
Distinguish an optional field from a contradiction. A display note saying that lamps might dim during tours might be welcome human context without any effect on the feed. If the machine representation instead declares the exhibit unavailable, check whether that is the same proposition or an invented equivalence. Define which values must agree, which are intentionally absent, and which may be rendered differently. A human-readable title can contain surrounding words such as “About the Lantern Label,” while the structured title preserves the record's plain name. A useful test doesn't have to normalize all human-friendly copy just to prove that both tell the intended story.
Load data for both representations from the same fictional source record where the design supports that. Give intentional derived values their own name and calculate them according to an explicit transformation. Doing this not only avoids brittle test duplication; it makes any differences easy to explain to someone responsible for content. If the HTML and data format use distinct editorial pipelines, verify that the late changes both reach the facets that need them. Two successful serializers are a technical accomplishment. They don't show that a later address or date correction reached both.
Make a second resource to prove the identity relationship matters. One example can be the lantern card and one a fictitious postcard cabinet with a different ID and public room. Asking each format to point to the correct name and room proves something a single reused hard-coded fixture can't. Don't turn this into a whole catalogue. Two small resources let you separate a route selection error from a representation error and make a plain-language failure report possible. If the second answer is JSON with the first exhibit's correct facts, the body type passed and the named resource failed. Write down that distinction so the first bug doesn't get assigned to documentation or media-type handling just because a test starts in a browser.
State the decision before writing assertions
Suppose the fictional policy says HTML is the default if Accept is missing or allows either format equally, JSON is preferred when it has the higher acceptable weight, and a request for neither supported type receives 406. This is a chosen application policy. HTTP Semantics, section 12 describes negotiation and how acceptability is signaled, but does not legislate HTML as a universal default. Other systems could intentionally behave differently. Put this local rule in the fixture README as a sentence so a later maintainer can distinguish a regression from a product decision.
Choose cases that distinguish preference from appearance. Start with JSON alone and HTML alone. Include two explicit types in both orders with opposite weights. Suppose the first request lists HTML first but assigns JSON a higher quality value. If both types are supported and otherwise equally specific, the invented server should choose JSON. Swap the values without changing the order and it should choose HTML. An implementation that takes the first comma-delimited token can pass both single-type cases while failing the paired ones. That pair helps isolate whether parsing or selection is at fault.
Include an explicit zero quality value. A type marked q=0 is not acceptable. There is a useful nuanced case where a specific exclusion and a broad wildcard coexist. In a mature framework, verify the intended precedence against its documented behavior before claiming that your test reflects every detail of the standard. For this compact fixture, select inputs whose expected results are clear enough for reviewers to reproduce and which your actual product intends to support. A poorly understood edge case can send a team into a permissive rewrite even when the actual supported clients would have been served correctly.
Write one explicit refusal case with Accept limited to an unsupported format. If the contract is 406, a default HTML page with status 200 is not equivalent. The product team may later change its refusal policy, but require that decision to be named. In the synthetic matrix, refusal should also avoid revealing production infrastructure details and use a small plain explanation. Tests should check that the success representation isn't silently returned after the refusal case and that a prior refusal doesn't poison subsequent acceptable requests. Caches should have clear instructions about whether a refusal can be stored. For this fixture, an explicit no-store refusal avoids widening the test's scope into negative caching.
The family of structured syntax suffixes offers a common source of confusion. RFC 6839 explains suffixes such as +json. A format using such a suffix can expose some generic processing properties without being identical to application/json as a representation contract. Avoid assuming that an invented vendor type was negotiated just because you can parse its body with a JSON parser. If your tool only intends to support ordinary application/json, confirm that clearly. Test a vendor type only when the interface promises it; in that case document whether fields, versions, and error semantics are different and add appropriate explicit rows.
Write refusal and default behavior as part of the user experience
Pick what a human reader can do when the requested representation cannot be offered. A refusal can be technically valid yet functionally useless if it doesn't name available forms or gives no route to find one. For a public guide, a short explanation can state that the service offers a document view and a JSON form. If you link to a stable human-readable route, give it an honest name. You could choose a response contract without alternate links where clients already know their allowed media types, but not because an error page fell out of an unrelated framework default. Put a clear local decision in the fixture.
A supported default may be chosen when no preference was expressed. Check the actual client path rather than inferring absence from the fact that a person didn't write request headers by hand. A browser, test runner or library can send its own preferences. Capture the effective request in your authorized local harness and distinguish “caller didn't set it” from “no Accept arrived.” An otherwise sensible default can appear incorrect when a fixture's HTTP helper injects a preference in the background. The log should show which condition the server actually saw and which part was created by the harness.
Use representative documented values, not an exhaustive assortment of every possible trivia case. A meaningful matrix can test equal supported preferences where the design has a tie policy, a stronger request for each supported format, a clear unsupported preference, and a common default. If a framework has support for more syntax than the product expects to document, that is not a reason to promise every interpretation to clients. If an unusual parameter needs support for a real consumer, build a relevant test based on the applicable standard and framework. Avoid growing a local helper into a partial HTTP parser purely for the sake of a notebook demonstration.
Separate refusal body and success body contracts. A browser presentation may explain the issue in ordinary text, and an API consumer may be able to parse a machine-readable error if the service specifically supports one. Do not instruct a data client that any body labeled JSON automatically represents the desired public exhibit. It should check the response class and documented answer shape before reading it as an item. Your local fixture can deliberately use a harmless synthetic refusal and verify that the client doesn't turn its explanatory fields into a blank catalogue row. The case matters even when no intermediary or validation is involved.
Test the contract before using a proxy
Work from the application outward. Run the fictional handler directly or over an ephemeral local loopback port. Use requests to the fixture endpoint only. For each request, record the request fixture ID, input Accept header or its absence, status, Content-Type, and which representation supplied the verified entity identifier. Do this in a table that a human can read. Add the matched contract rule as an expected value in the fixture specification, not as a secret string sent by the production endpoint. If you only capture a final green marker, it takes longer to find the broken rule once the harness is extended.
Verify baseline traces in which nobody has already called the handler. If the fixture runner inadvertently reuses application state across cases, it can make a header bug look like a cache bug. A simple reset or fresh instance separates the request-level cases. Keep effective query, host, and path the same as far as the fixture is concerned. If the JSON case uses ?format=json and the HTML case does not, a proxy may store two entries because the URLs differ. That is a perfectly reasonable alternative interface, but no longer tests the content variation intended here.
When you inspect Content-Type, separate the parsed media type from optional parameters. An HTML response of text/html with a charset is still HTML. The important assertion is its type and expected character decoding, not exact formatting or casing of the parameter string. Use a non-ASCII sample in a separate trial if your contract promises UTF-8, for instance an invented exhibit subtitle with a macron. Likewise, header and media type casing should not cause a branch to misidentify the representation. Prefer parser helpers available in your tooling instead of rewriting HTTP handling for a fixture.
Verify that a successful representation carries Vary containing Accept if the response depends on that request header and may interact with caches. Vary is not an instruction to split bytes or generate a type. It tells a downstream cache what aspect of the choosing request matters for deciding whether a stored response can satisfy a later one. HTTP Caching, section 4.1 explains matching for stored responses and differing request header fields. A representation can be selected correctly by the application and still be reused incorrectly if the information delivered to consumers is incomplete.
Check Vary as a list of field names, not a direct string equality with Accept. Servers or intermediaries may also vary by compression, represented by Accept-Encoding. Adding Accept should retain already-required variation rather than overwriting other names. Keep the fixture's compression simple so the test is not accidentally making claims about compression. The exercise can preserve an extra harmless Vary slot to catch header replacement without implementing any compression at all. If Vary contains an asterisk, treat it as a separate design and test, not as a convenient substitute for proving a cacheable match.
Exercise what the real client thinks it received
The fixture should do more than print status and Content-Type. A simple browser-facing check can assert an expected heading from a parsed document and one stable identifier that can be associated with the intended item. For a structured response, parse the body with the client's ordinary JSON parser and verify the expected field relationship. Do not assume that a response labeled with the right type is valid on those facts alone. An exception handler can produce plain text, a renderer can put wrong data in a valid shape, and a response in the wrong resource context can still look beautiful on screen.
Try a tiny consumer repair exercise. Give staff a small local output named “exhibit card response” and ask what proof they would use before putting its room into a training handout. If the proof is “I see the right words from an old caption,” they haven't established it came from the currently requested item. If it is “the parser says success,” they haven't established those words are the right ones. Ask for the smallest check that ties request identity, response class, representation and value together. This can be written in one line in the fixture documentation; its role is to prevent pleasant recognition from taking the place of evidence.
An actual HTML page may include a warning or editorial highlight that the data view represents in another way. Use scoped inspection, not a full byte comparison across renderings. Decide how to test what must remain stable if an editor changes punctuation or wraps the heading. A strict comparison across every printed string increases maintenance without making the core promise stronger. Equally, a search for a single word in any part of the response can pass on navigation breadcrumbs or an unrelated quote. Match the name in the relevant element and the object field defined by the content contract. This is how a synthetic fixture stays both small and meaningful.
Warm the fixture both ways
Once origin-level assertions pass, introduce a tiny reuse component whose only job is to store eligible synthetic success responses and select them using the named request field. It is not a general HTTP cache. Label it accurately and restrict it to the example. Give the component a trace counter for how often it called the local origin. In the first run, ask for HTML, ask for JSON, then repeat the HTML request. For the chosen fixture routes and storage policy, the first two reach the local origin and the repeated identical choice can be reused. The last HTML request still needs to be asserted as HTML rather than merely counted.
In a fresh run ask for JSON, then HTML, then repeat JSON. Record all three outcomes and counters. An unreliable single-route object store keyed only by URL might pass the first two direct origin cases and even the first response in each sequence. Sequence testing is what makes the missing Vary contract observable. In a demonstration fixture, include an explicitly labeled broken control that intentionally ignores variation. If it fails after the first request in both runs, you have evidence that the test catches the intended error. When a known broken control passes, improve the test before trusting a passing implementation.
The treatment of absent headers deserves its own miniature trace. Ask once with no Accept, then for JSON, then with no Accept again. Under the fictional contract the two absent-header requests should agree with the documented default. The absent header is not an unknown typo to discard from the logs. It is an input class, and it differs from an explicitly specified field even when both happen to produce HTML in the fixture. Variation based on exact header values may split requests that produce the same representative body; that is a question about efficiency, separate from whether one format can wrongly mask another.
Be cautious about concluding anything from a trace that never demonstrates reuse. If the toy cache regards all responses as uncacheable, repeated calls can still return the correct types without showing that the cache finds the intended matching objects. That is why the origin counter and a deliberately eligible synthetic response belong in the fixture. Conversely if the product intentionally chooses not to cache, a no-reuse outcome is not a bug. In that case the meaningful contract is verified Cache-Control behavior under the real authorized preview and normal consumers, not a simulated green cache hit.
A distinct case: choose between a shared URL and a stable data link
Imagine a local map collection with a short caption about a footbridge. A neighborhood exhibit puts the caption in an HTML card. An authorized volunteer tool reads a simple structured input to prepare draft signs. In the fictional design, its author controls the tool but cannot be sure every future volunteer client will specify the intended preference. The catalog maintainer is deciding whether to support one negotiated card URL or an explicit data route. Before building a local negotiation test, they clarify who needs to copy which addresses and what older supported tools already expect.
A trace in the controlled test starts with an interactive browser that asks appropriately and sees the card. The next check uses the actual command wrapper, which sends no preference. Under the existing documented default it correctly receives HTML. This is not a failure of negotiation. The wrapper should request JSON or use the independently advertised data route. The key lesson differs from the lantern example: choosing a correct default server answer doesn't guarantee the consuming client made the right request. A test written only against a driver that forces a header could hide the practical integration problem.
The team decides to expose a stable explicit data link for that audience while preserving the public document link. The data URL returns the expected object according to its own described policy. The ordinary exhibit address remains copyable as a page. If there are existing approved clients for negotiation, keep their path safe during a deliberately scoped transition rather than silently mapping both to one form. A regression fixture can check both route paths and name which choices they keep compatible. That evidence is much more useful than insisting that every smaller system needs more negotiation or that every negotiated endpoint needs to split.
You can also choose not to split a well-understood contract. If both supported clients reliably request their representation and the resource identity is clear, the shared route might be the simpler user-facing story. Write why it remains useful instead of treating URL count as a performance measure. A short comparison records the audience, their actual request behavior, and the supported output or error on each path. Maintain it together with the relevant consumer. This gives the next person a reason why an apparently redundant data URL exists and what would need review before retiring it.
Separate validator questions from format selection
Entity validators and conditional requests can make variant mistakes harder to interpret. If you add conditional checks, start after the unconditional cases have made the two representations distinguishable. Record a validator from an HTML response, then make the specific request for the intended representation using its own known validator. Choose the semantics appropriate to your application and HTTP preconditions. A 304 response has no representation body, so treat it as a different assertion from a successful HTML or JSON body. Don't mislabel an empty 304 as content corruption simply because it was tested with the body parser.
Make the control deliberately simple. The fixture may be most useful without implementing conditional requests at all. Validate ordinary successful byte and entity behavior first, and leave an explicit untested box in the worksheet for revalidation or stale responses. It is far better to report what was left out than to suggest a two-row success trace certifies every behavior of a shared edge deployment. A later integration check can collect real headers and compare them against the named contract within a permitted preview. It can use an existing staging setup rather than altered production or scans of unrelated domains.
You may encounter a vendor cache that ignores or transforms particular headers, a framework that sets default responses differently, or client libraries that supply their own broad defaults. The fixture cannot predict that. Inspect the effective request at the component under study, and keep the comparison tied to the input actually sent, not the input thought to have been sent. Document the client version if its headers are part of the problem. Then label the two tests separately: contract tests prove the intended behavior in a controlled local lane, and integration tests show the behavior of a specific system at a specific time.
Check time and revision independently from the response format
A small cache illustration can prove fresh legitimate variant selection without covering change over time. The resource owner needs an additional test if the public room changes during an exhibit. In a controlled local design, define when the edit should become visible and through which publication mechanism the relevant forms are refreshed. Both representations can be validly selected and still display different revisions after an isolated update. Distinguish “correct representation” from “current according to this resource's release policy.” A single top-level status or count of requests doesn't prove either on its own.
Use a deliberate fictional update rather than a production edit to make the question concrete. In revision 1 both resource forms refer to Room A. In revision 2 the publisher moves the lantern to Room B. If your approved local test expects both to show Room B immediately after a controlled release, record the actual observer's timeline and context. If the real product permits a bounded stale window, document it, and set the expected outcomes accordingly without inventing a stricter claim than intended. A test can make time deterministic in a harness or verify a defined transition in a permitted staging environment. Label that limitation in the receipt.
An editor should not have to understand validator syntax to interpret the failure. “Interactive exhibit card shows Room B; accepted test data link still shows A after the planned change boundary” gives a concrete inconsistency to investigate. The technical trace can name which response fields or diagnostic counters were observed. It should also record when a measurement comes from a stand-in rather than an actual deployed intermediary. There is no need to test someone else's infrastructure to establish a useful local comparison. Building a controlled fixture protects the real service and makes the cause easier to isolate.
Retain the last expected revision in a form that is easy to check if the local example grows. Recording exact current representation bodies is unnecessary when stable source facts and relevant response fields suffice. A small assertion over one changed and one unchanged property helps maintain trust. The expected room changed; the exhibit ID did not. That difference is the kind of specific evidence that lets a maintainer separate publication mistakes from negotiation mistakes without repeatedly warming the entire service.
Keep the record small enough to run again
A reproducible fixture has an intentionally narrow receipt. Include the fictional payload version, media type policy, request case IDs, and the exact reset boundary. Indicate whether an origin or reuse component answered each request. A good failure states that request sequence two, step two, asked for HTML and received a JSON Content-Type after the JSON response had been stored; it also states whether the origin counter moved. That message can distinguish a request parser bug from a storage selection bug faster than a generic assertion labeled wrong response.
Add an expected invariant that belongs to the resource. Both forms must return exhibit-07 and accurately preserve the public room name. Add another invariant that belongs to presentation. HTML has the document heading; JSON has the expected object. Name the property that should vary, and the one that should stay constant. This is often the missing step in a reproduction where two outputs are compared as if the only valid response were a single normalized byte string. Representation variation is deliberate, and the test should defend it rather than trying to erase it.
Start with two formats and a short run in each order. Save the tests alongside the contract and keep real access tokens, private traffic, production cookies, and customer material outside the fixture. An invented label, a dozen small assertions, and a clearly faulty control are enough to explain why the test matters. When it fails, a reviewer can see precisely whether the wrong choice was made, the right choice was mislabeled, or the right choice was saved and reused for the wrong later request. Those are different fixes. The fixture pays for itself the first time the team stops treating those failures as interchangeable.
Mark which conclusions belong to layer and which belong to the product
Before filing the test result, read it twice: once as the maintainer who knows the fixture, and once as a volunteer who only cares about the card or data. “Returned expected cache header” makes sense in a layer receipt. “The tool received the published room assignment in its documented JSON format” is a product result and needs an observed consumer path to support it. Do not let the first sentence quietly become the second. A test failure should distinguish unexpected header, unexpected representation, unexpected fact, or missing support for the intended route. These send people to different owners even though they can all present as a disappointing answer.
Keep unsupported conditions visible. A local run with two public formats and an invented resource cannot establish behavior for authenticated routes, other media types, or intermediaries that aren't part of the run. State those gaps once, without describing unrelated exploratory actions. Make it clear whether a responsible reviewer can add another public scene to the test without changing the policy. A narrowly scoped repeatable result is stronger than a broad assurance whose only evidence is a toy timestamp or a familiar header printed in a log.
Treat headers as observations you can compare, not boilerplate copied into a screenshot
A response's Content-Type expresses the form the sender says is being returned. What should be present on an HTML success may differ from the description of a refusal or an empty conditional response. When a synthetic matrix records the header, include the status, named case, and what the intended consumer made of the body when there was one. This gives you three compatible facts instead of a screenshot filled with miscellaneous fields. It also avoids comparing header string character-for-character when the useful decision is whether the response has the expected declared role and can be consumed as intended.
Record variation separately from caching approval. A rule that asks a shared layer to distinguish responses by one request header does not itself say how long any response is appropriate to reuse or that the team wants reuse. If reuse is deliberately absent in your example, teach the fixture what reliable fresh behavior to expect and don't set up counters requiring a hit. Where you do model reuse, different but legitimate requests might select the same representation. Whether the model stores them together can be an efficiency question. Both consumers receiving their expected format and facts is the correctness question. Keep that distinction in the review.
If forwarding or preferences change in a deployed product, use the responsible support path and an authorized preview or local stand-in to gather aligned evidence. Measure the request actually observed at the appropriate component rather than inferring it from consumer code. Source control can establish which version of an assertion exists, not what an independently cached response contained at a particular time. The receipt should identify whether it describes local fixture, staging integration, or observed ordinary use. Don't convert one into another in a status message.
Simplify when the product contract changes. If the only real consumer of an extra format has migrated to another route, the product owner may choose to leave a documented transition or retire old negotiation behavior. A backward compatibility check should give that choice its own result. Passing a fixture for a feature nobody should use doesn't by itself justify preserving it indefinitely. The fixture has done its most important work when it made the exact promise visible enough to maintain or intentionally change.
Primary sources
- IETF HTTP Semantics: Content Negotiation
- IETF HTTP Caching: Calculating Cache Keys With Vary
- IETF Additional Media Type Structured Syntax Suffixes
AI disclosure: Drafted with AI assistance for Apiary using public standards and invented examples.