A MIME type, also called a media type, identifies the format and general nature of data in an HTTP request or response. For example, application/json indicates that a body contains JSON. In OpenAPI, declaring the media type makes request and response formats visible to documentation tools and provides the place to attach a schema. section 6.6.2 section 9.7.1
Choosing JSON or XML
A transfer API can accept XML when a banking system sends Content-Type: application/xml, while returning XML or JSON according to the consumer’s Accept header. Request and response formats do not need to match. A transaction endpoint might return JSON by default but provide CSV when a spreadsheet-oriented consumer requests Accept: text/csv. section 9.7.1
Use media types to make format choices explicit and useful to consumers:
- Declare application/json with a schema for structured request or response data. section 6.6.2
- Support only formats that fit the operation, while keeping format behavior consistent across related operations. section 9.7.1
- Offer alternate representations such as application/hal+json or application/vnd.siren+json through content negotiation. section 11.4.4
- Describe raw files with types such as application/pdf, image/png, image/jpeg, image/*, or application/octet-stream. section 14.3.4
Listing 14.1 Sending a file in a request body
paths:
/files:
post:
requestBody:
content:
application/pdf: {} #1
image/png: {} #1
image/jpeg: {} #1
responses:
"201": #2
description: File uploaded
This OpenAPI listing shows how an upload operation accepts PDF, PNG, and JPEG bodies by declaring each media type under content. section 14.3.4
