skip to content

When an OpenAPI operation offers several media types, what does Postman's importer put in the request body?

level: seniorimportance: should knowfreq 36%

answer

  1. Many accepted formats, one body slot
  2. The converter must collapse a set
  3. The loss is silent and unrecorded
  4. An import option picks the winner
  5. The definition stays the authority afterwards

basics

~20 s

One body only. A collection request holds a single body in a single mode, so an operation offering several media types loses all but one on import, and preferredRequestBodyType is the converter option deciding which survives.

solid answer

~40 s

This is the clearest **information loss** in the whole import. A definition can describe one operation as accepting several media types; a collection request holds **one body in one mode**. The structures do not correspond, so the converter must choose, and `preferredRequestBodyType` is the option that makes the choice. Whatever it picks is what appears in the generated request; the alternatives are simply absent from the collection, with nothing recording that they existed. The senior move is to expect the loss rather than discover it: if callers genuinely use two media types against the same operation, one imported request will never cover both, and you keep a hand-made second request beside it. Re-importing regenerates the converter's choice, not yours.

go deeper

for a junior

Be ready to say that a request carries one body, so an import has to pick a single media type when the definition offers several, and an option controls which one it picks.

for a middle

Explain the collapse as a structural mismatch rather than a limitation: the definition documents everything accepted, a request represents one concrete call, and preferredRequestBodyType resolves many into one.

for a senior

Demonstrate that you plan for the loss. Set the preference to match real caller behaviour, add hand-made requests where a second format matters, and keep pointing people at the definition as the authority.

for a principal

Own the policy question: if imported collections circulate as the working reference for an API, decide what a lossy projection is allowed to be used for, and where the authoritative answer about accepted formats lives.

## Two structures that do not correspond An OpenAPI operation can describe more than one acceptable payload format for the same endpoint: the definition's content mapping is keyed by media type, and several keys may sit under one operation. A collection request is not shaped that way. It holds **one body, in one mode** — a single payload with a single interpretation. There is no place in a request for a second alternative body waiting to be selected. That mismatch is not a bug on either side. Each structure is right for its job: a definition documents everything a server will accept, while a request represents one concrete call you are about to make. The import sits between them and has to collapse a set into a single element. ## What `preferredRequestBodyType` does The converter exposes that collapse as an option. `preferredRequestBodyType` states which media type wins when an operation offers more than one, and the generated request is built around that choice. | The definition side | The collection side | |---|---| | several media types under one operation | exactly one body on the request | | every accepted format documented | the one the option preferred | | alternatives visible to any reader | alternatives absent, unrecorded | The third row is the one to internalise. The loss is **silent**. A generated request does not carry a note saying "this endpoint also accepts another format"; it simply contains the winner. Read the collection alone and you cannot tell whether the operation ever offered a choice. ## Why this is a senior-level concern The mechanics are simple. What makes it a production question is what teams do with imported collections afterwards: - **The collection becomes the reference.** Someone new reads the imported requests instead of the definition and concludes the API accepts only one format. - **The other format goes untested.** A run of the imported collection exercises exactly one media type per operation, so a defect in handling the other one is invisible to that run. - **Hand edits do not survive regeneration.** Add the missing alternative by hand and it lives only in that copy; a fresh conversion produces the converter's choice again, knowing nothing of your addition. - **The choice is invisible in review.** Two engineers importing with different preferences produce collections that disagree, and the diff looks like an API change rather than an option change. ## Working with the loss 1. **Decide the preference deliberately** and record it with the collection, so the generated body matches what your callers actually send rather than whatever the default happens to prefer. 2. **Add a second request by hand** when both formats genuinely matter, and label it clearly as hand-made so nobody expects the next import to reproduce it. 3. **Treat the definition as the authority** on what the endpoint accepts. The collection is one projection of it, and the projection is lossy by construction. 4. **Say so when you hand the collection over.** "One body per request, the rest were dropped at import" is the sentence that prevents the wrong conclusion later. ## Where the boundaries fall This question sits precisely on a seam, and it is worth being explicit about both sides of it: - **How a definition expresses multiple media types** — the content mapping, its keys, and how a payload's shape is described under each — is a question about the OpenAPI document, and belongs there rather than to the importer. - **How a collection request expresses its single body** — which modes exist and how a payload is stored under each — is a question about the collection's body structure, which is the same whether the request was imported or typed by hand. - **The import owns only the collapse**: many to one, decided by `preferredRequestBodyType`, with nothing left behind to mark what was dropped. ## The short answer The imported request holds one body in one mode, chosen by `preferredRequestBodyType`. Every other media type the operation offered is absent from the generated collection, and no record of the alternatives survives the conversion — so the definition, not the collection, remains the truth about what the endpoint accepts.

  • Your callers genuinely send two different media types to one endpoint. How do you cover both in an imported collection?
    You cannot, from one import. A request holds one body in one mode, so you set the preference to whichever format matters most and add a second request by hand for the other. Label the hand-made one, because a fresh conversion regenerates only the converter's choice.
  • Why is this loss more dangerous than the folder shape or the request names an import chooses?
    Because names and folders are obviously cosmetic, while a missing media type looks like a statement about the API. Nothing in the generated request says an alternative existed, so a reader treating the collection as reference concludes the endpoint accepts only one format.

saying these in an interview costs you the question

  • Says the importer generates one request per media type
  • Claims a request can hold several alternative bodies
  • Thinks the dropped media types are recorded somewhere
  • Treats the imported collection as authoritative over the definition
  • Expects hand-added requests to survive a fresh import