Operations & Systems

HTTP Accept Headers for Business Exports: Request the Format and Check What Came Back

An export owner asks for JSON. The service sends CSV. The receiving job has a CSV parser somewhere, so someone suggests accepting the file and moving on.

The missing question is whether that receiver has an agreed CSV contract for this export.

A format preference belongs in the request. Evidence of the received format belongs in the response record. Business acceptance needs both records and the contract that connects them.

RFC 9110 section 12.5.1 defines Accept as a way to express response media-type preferences. It does not make those preferences proof of what arrived.

The worksheet below is a proposed planning method for a fictional read-only export. Every exchange, record, and operating rule is synthetic. No request was executed against a live service.

Put the Request and Response Fields on Different Lines

In these examples, Accept appears in the request. It states which response media types the client prefers. Content-Type appears in a response that carries an export. It describes the associated representation.

A GET request does not need a JSON request body to ask for a JSON response. Adding Content-Type: application/json to an empty request does not replace an Accept preference.

RFC 9110 section 8.3 defines Content-Type in terms of the associated representation. Keep that meaning separate from the request preference defined for Accept.

Write the expected response type in the endpoint contract. Then record the actual response type when it arrives. A request log containing Accept: application/json cannot fill both fields.

This boundary belongs in API-first business operations before the export feeds another task. The receiving owner needs to know which formats it can interpret under an agreed contract.

Start with the provider's documented capabilities. Accept cannot establish that an endpoint offers CSV, JSON, or any other format. An unsupported wish remains a wish until the service contract supports it.

List Supported Formats Before Ranking Them

For the fictional endpoint, assume its documented contract offers two representations of one planning snapshot: application/json and text/csv. The example chooses those capabilities. It does not describe an actual provider.

The JSON receiver expects an object with a snapshot date and an item array. The CSV receiver expects exact headers and a date on each record. Both represent the same two invented item quantities.

Each receiver needs its own validation rules. A CSV file is not approved merely because the application can open a spreadsheet. A JSON object is not approved merely because parsing succeeds.

Use the CSV handoff contract to define headers, missing values, record identity, and reconciliation. Keep those decisions available before declaring CSV an acceptable fallback.

If the business approves only JSON for an automated consumer, send a narrow preference and enforce that restriction on receipt. A broader export viewer can use a different preference when its owner approves both formats.

Give those consumers separate names in the worksheet. Otherwise a permissive setting for manual inspection can become an accidental policy for an operational import.

Read Media Ranges and Quality Values Together

Accept can name an exact media type, a type-wide range such as text/*, or the general range */*. RFC 9110 section 12.5.1 defines those ranges and their precedence.

A q value expresses relative preference. Section 12.4.2 defines values from zero through one. An omitted q value means one. Zero means unacceptable under the expressed preference.

The synthetic preference below ranks JSON above CSV and excludes other media types:

Accept: application/json, text/csv;q=0.7, */*;q=0

JSON receives quality one because its range has no explicit weight. CSV receives quality zero point seven. An HTML representation matches only the general range, which gives it quality zero.

These values are preferences, not confidence scores or promised percentages. Zero point seven does not mean a seventy percent chance of receiving CSV. It does not evaluate the quality of the business records.

When several ranges match a type, the most specific matching range determines its quality. This matters when a broad range and a narrow exclusion appear together.

Consider a second synthetic preference:

Accept: text/*;q=0.4, text/csv;q=0, application/json;q=1

CSV matches both text/* and the exact text/csv range. The exact range takes precedence, so CSV has quality zero. HTML matches text/* and has quality zero point four. JSON has quality one.

Do not include that broad text range when the receiver accepts only JSON and CSV. The header would express acceptance of other text types. Keep the preference aligned with the actual receiver contract.

Walk Through Synthetic JSON and CSV Exports

These are synthetic HTTP excerpts. Unrelated fields are omitted. The relative target identifies no live service, and all records are invented.

The first synthetic request asks only for JSON:

GET /exports/planning-snapshot HTTP/1.1
Accept: application/json

The corresponding synthetic response honors that preference:

HTTP/1.1 200 OK
Content-Type: application/json
Vary: Accept

{"snapshot_date":"2026-10-27","items":[{"item_id":"P-01","quantity_units":12},{"item_id":"P-02","quantity_units":8}]}

The receiving job records JSON as both requested and received. It still checks parsing, required fields, snapshot date, and the intended record coverage. The displayed quantities total twenty units across two items.

The second synthetic request comes from the fictional receiver with an approved CSV contract:

GET /exports/planning-snapshot HTTP/1.1
Accept: text/csv

Its synthetic response selects CSV:

HTTP/1.1 200 OK
Content-Type: text/csv; charset=utf-8
Vary: Accept

item_id,snapshot_date,quantity_units
P-01,2026-10-27,12
P-02,2026-10-27,8

The response declares a charset parameter alongside the CSV type. The receiver checks that declaration against its format contract. It does not discard parameters before deciding whether it supports the representation.

Both excerpts display two data records and twenty known units for the same snapshot date. That agreement is visible in these synthetic samples. It is not evidence that an unspecified provider keeps every export format equivalent.

If the endpoint uses different fields or coverage across formats, record that difference. The business may need separate acceptance criteria rather than a universal fallback switch.

Compare a Fallback With a 406 Response

Suppose the JSON-only receiver sends Accept: application/json, but the fictional endpoint currently has only CSV available. Two possible outcomes need separate response paths.

The server can honor the negotiation constraint by returning 406 Not Acceptable. RFC 9110 section 15.5.7 describes this status when no current representation is acceptable and the server declines to supply a default.

The server can also disregard the preference and return another representation. Section 12.4.1 explicitly permits that choice. An unavailable preferred format does not always require a 406 response.

Synthetic outcome Observed result Proposed receiver decision
Preference honored 200 with JSON after JSON-only Accept Continue to validation
Preference disregarded 200 with CSV after JSON-only Accept Hold for a format mismatch
Negotiation refused 406 because no acceptable representation is available Record negotiation failure; accept no export

A two hundred response with CSV does not become acceptable to the JSON-only receiver because HTTP permits the server's choice. The receiving contract still excludes that format.

Likewise, a 406 is not an empty snapshot. It records a negotiation outcome. Leave the previous accepted snapshot identified by its original date.

For a receiver that permits JSON and CSV, a correctly declared CSV response can continue to CSV validation. That permission comes from its approved contract. It does not come from discovering a parser after the mismatch.

Observe Vary Without Turning It Into a Guarantee

A response can include Vary: Accept when the request's Accept field might have influenced representation selection. RFC 9110 section 12.5.5 defines Vary and its implications for response reuse.

At planning level, record whether format selection depends on request fields. A service returning JSON and CSV from one target needs its representation choices understood wherever responses are stored or reused.

The worksheet should capture the observed Vary value, including absence. Its presence does not prove that the body matches Content-Type. Its absence does not prove that the endpoint has only one format.

Leave cache implementation to a separate design review. This article does not specify a cache key, cache lifetime, or intermediary configuration. Those choices require the applicable caching contract and runtime evidence.

Keep freshness validation separate from format selection. Conditional requests with ETags address reuse of a saved representation. An entity tag does not express a preference for JSON instead of CSV.

A planning review should identify who owns each question. The export owner defines acceptable representations. The integration maintainer verifies observed metadata. The storage owner resolves reuse rules under the actual service configuration.

Copy the Negotiation Worksheet

Use one worksheet for each consumer and endpoint contract. Attach attempt records when comparing observed responses. The table is a proposed agreement, separate from the HTTP standard.

Field Record before and after the exchange
Endpoint contract Named endpoint, method, version, business purpose
Supported media types Provider-documented formats and receiver-approved formats, listed separately
Accept Exact request preference, including ranges and quality values
Received type Full Content-Type and observed status
Fallback Approved alternate parser and contract, or explicitly none
Vary observation Actual field value, absent, or not inspected
Acceptance decision Checks completed, unresolved conditions, disposition, and owner

For the synthetic JSON-only request, record only JSON as receiver-approved. If CSV arrives with status 200, record the mismatch and hold the response. Vary can be present while acceptance still fails.

For the synthetic CSV request, record the CSV header contract and supported charset. Compare the two displayed identifiers, the date, and the twelve-plus-eight total after parsing. Keep wider coverage unresolved until checked.

For the weighted preference, record JSON quality one, CSV quality zero point seven, and other types quality zero. If CSV arrives, continue only because the receiver already approves that fallback.

Missing observations stay missing. Do not fill the received-type field from the Accept header. Do not infer Vary from the fact that two formats were documented.

Review a changed provider contract before changing the consumer preference. Adding a format can require new field mappings and business checks. Update the worksheet with the accepted contract version and the evidence used.

Request the format. Verify the response.

Sources

Topic map: APIs, webhooks, and automation

Articles in this cluster, then the 3 clusters that share the most topics with it.

This cluster: APIs, webhooks, and automation

Neighbor: CRM and pipeline data

Neighbor: Spreadsheets, CSV files, and data handoffs

Neighbor: Records, access, and continuity