Skip to content

Commit 81efe22

Browse files
LukeHagarLukeHagar
authored
Merge pull request #13 from ritza-co/content-and-media-types
add content and media types
2 parents 90e93b9 + 46b8b2b commit 81efe22

File tree

1 file changed

+253
-15
lines changed

1 file changed

+253
-15
lines changed

‎reference/paths/operations/content.md

Lines changed: 253 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,276 @@
1-
# Content & Media Types
1+
# Content and Media Types in OpenAPI
22

3-
A map of Media Types (including wildcards) to a [Media Type Object](/openapi/paths/operations/content#media-type-object) that describes the content of the request or response as it relates to the media type consumed or produced.
3+
In OpenAPI 3.1, the `content` keyword indicates the media types required in request bodies or returned by responses. Media types are often referred to as content types or MIME types, but we'll use media types in this document.
4+
5+
Media types in OpenAPI inform the client how to interpret data received from the server, and which data types the server expects from the client.
6+
7+
Common examples of media types include:
8+
9+
- `application/json` for JSON objects.
10+
- `text/plain` for plain text.
11+
- `image/png` for PNG image files.
12+
- `application/xml` for XML files.
13+
- `multipart/form-data` for form data that can include files.
14+
15+
## Content Map
16+
17+
The `content` object is a map of key-value pairs.
18+
19+
Each key in the map is a [media or MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) like `application/json`, `text/plain`, or `image/png`.
20+
21+
The value associated with each key is a [Media Type Object](#media-type-object) that describes the structure and other relevant details for its corresponding media type.
22+
23+
Media type keys can include wildcards indicating a range of media types they cover. For example, `application/*` would match `application/json`, `application/xml`, and so on, and `*/*` would match any media type. It can be explicitly defined to match only a single media type, for example, `application/json; charset=utf-8`.
24+
25+
26+
**Avoid wildcard media types where possible:** While using wildcards in defining content types is convenient, it might lead to ambiguous results if the client and server do not handle the same range of media types. Use specific media types where possible to avoid ambiguity.
427

5-
The key in the map is a [media or MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) that determines how the content is encoded. This media type can include wildcards indicating a range of media types it covers. For example, `application/*` would match `application/json`, `application/xml`, and so on, and `*/*` would match any media type. It can be explicitly defined to match only a single media type, for example, `application/json; charset=utf-8`.
628

729
Where both a wildcard and a specific media type are defined, the specific media type definition takes precedence.
830

9-
For example:
31+
The example below shows a `content` map with four media types:
1032

1133
```yaml
1234
content:
13-
application/json: # Upload a JSON file
35+
application/json: # JSON formatted content
1436
schema:
1537
$ref: "#/components/schemas/Drink"
16-
img/*: # Upload any image format
38+
img/*: # Image formatted content of any type
1739
schema:
1840
type: string
1941
format: binary
20-
text/*: # Upload any text-based description of a drink
42+
text/*: # Text-based content of any type
2143
schema:
2244
type: string
23-
text/csv: # Upload a CSV file (this will take precedence over text/*)
45+
text/csv: # CSV formatted content (this will take precedence over text/*)
2446
schema:
2547
$ref: "#/components/schemas/Drink"
2648
```
2749
50+
In this example, the server expects one of the following types:
51+
52+
- A JSON object representing a drink.
53+
- Any image file in binary format.
54+
- A CSV file representing a drink.
55+
- Any text file.
56+
57+
## Content Negotiation
58+
59+
When the client sends a request to the server, it includes a `Content-Type` HTTP header in the request, indicating to the server how to interpret the data in the body of the request.
60+
61+
Likewise, the server includes a `Content-Type` HTTP header in its response, which the client should use to interpret the data in the response.
62+
63+
The client may also include an `Accept` HTTP header in a request, indicating to the server which content types the client can handle. The server should then send a response with a `Content-Type` header that matches one of the accepted types. This exchange is known as [content negotiation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation).
64+
65+
The diagram below illustrates the headers sent by the client and server during content negotiation:
66+
67+
```mermaid
68+
sequenceDiagram
69+
participant C as Client
70+
participant S as Server
71+
Note over C,S: Establish Connection
72+
C->>S: Request with Headers
73+
Note over C: Request headers include:
74+
Note over C: Content-Type: text/csv
75+
Note over C: Accept: application/json, application/xml
76+
S->>C: Response with Headers
77+
Note over S: Response headers include:
78+
Note over S: Content-Type: application/json
79+
```
80+
81+
Note that the request and response content types do not need to match. For example, in the diagram above, the client sends a request as CSV but expects JSON or XML in response.
82+
2883
## Media Type Object
2984

3085
A Media Type Object describes the request or response for a media type, with optional examples and extensions.
3186

32-
| Field | Type | Required | Description |
33-
| ---------- | ------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
34-
| `schema` | [Schema Object](/openapi/schemas) | | A schema that describes the request or response content. |
35-
| `example` | Any | | An optional example of the media type. This example overrides any examples from the [Schema Object](/openapi/schemas) in the `schema` field. Mutually exclusive with the `examples` field. |
36-
| `examples` | Map[string, [Example Object](/openapi/examples) \| [OpenAPI Reference Object](/openapi/references#openapi-reference-object)] | | Optional examples of the media type. These examples override any examples from the [Schema Object](/openapi/schemas) in the `schema` field. Mutually exclusive with the `example` field. |
37-
| `encoding` | Map[string, [Encoding Object](/openapi/paths/operations/requests#encoding-object)] | | An optional map of [Encoding Objects](/openapi/paths/operations/requests#encoding-object). Each Encoding Object's key should match one of the properties from the [Schema Object](/openapi/schemas) in the `schema` field. Only applies to [Request Body Objects](/openapi/paths/operations/requests) when the media type is `multipart` or `application/x-www-form-urlencoded`. |
38-
| `x-*` | [Extensions](/openapi/extensions) | | Any number of extension fields as required by tooling and vendors. |
87+
| Field | Type | Required | Description |
88+
| ---------- | ---------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
89+
| `schema` | [Schema Object](../../schemas.md) | | A schema that describes the request or response content. |
90+
| `examples` | Map[string, [Example Object](../../examples.md) \| [OpenAPI Reference Object](../../references.md#openapi-reference-object)] | | Optional examples of the media type. These examples override any examples from the [Schema Object](../../schemas.md) in the `schema` field. Mutually exclusive with the `example` field. |
91+
| `example` | Any | | An optional example of the media type. This example overrides any examples from the [Schema Object](../../schemas.md) in the `schema` field. Mutually exclusive with the `examples` field. Deprecated in OpenAPI 3.1 in favor of `examples`. |
92+
| `encoding` | Map[string, [Encoding Object](./requests.md#encoding-object)] | | An optional map of [Encoding Objects](./requests.md#encoding-object). Each Encoding Object's key should match one of the properties from the [Schema Object](../../schemas.md) in the `schema` field. Only applies to [Request Body Objects](./requests.md) when the media type is `multipart` or `application/x-www-form-urlencoded`. |
93+
| `x-*` | [Extensions](../../extensions.md) | | Any number of extension fields as required by tooling and vendors. |
94+
95+
## Media Type Examples
96+
97+
The examples below illustrate the use of the `content` object with different media types.
98+
99+
### JSON Media Type
100+
101+
The example below shows a `content` object with a JSON media type:
102+
103+
```yaml
104+
content:
105+
application/json:
106+
schema:
107+
$ref: "#/components/schemas/Drink"
108+
examples:
109+
mojito:
110+
value:
111+
name: "Mojito"
112+
ingredients:
113+
- name: "White Rum"
114+
quantity: 50
115+
- name: "Lime Juice"
116+
quantity: 20
117+
- name: "Mint Leaves"
118+
quantity: 10
119+
```
120+
121+
In this example, the server expects a JSON object representing a drink. The `examples` field provides an [Example Object](../../examples.md) of the expected JSON object.
122+
123+
The curl command below sends a request to the server with a JSON object in the body:
124+
125+
```bash
126+
curl -X POST "https://api.example.com/drinks" \
127+
-H "Content-Type: application/json" \
128+
-d '{
129+
"name": "Mojito",
130+
"ingredients": [
131+
{
132+
"name": "White Rum",
133+
"quantity": 50
134+
},
135+
{
136+
"name": "Lime Juice",
137+
"quantity": 20
138+
},
139+
{
140+
"name": "Mint Leaves",
141+
"quantity": 10
142+
}
143+
]
144+
}'
145+
```
146+
147+
### Image Media Type
148+
149+
The example below shows a `content` object with an image media type:
150+
151+
```yaml
152+
content:
153+
image/png:
154+
schema:
155+
type: string
156+
format: binary
157+
```
158+
159+
In this example, the server expects an image file in binary format.
160+
161+
The curl command below sends a request to the server with an image file in the body:
162+
163+
```bash
164+
curl -X POST "https://api.example.com/images" \
165+
-H "Content-Type: image/png" \
166+
--data-binary @image.png
167+
```
168+
169+
### Text Media Type
170+
171+
The example below shows a `content` object with a text media type:
172+
173+
```yaml
174+
content:
175+
text/plain:
176+
schema:
177+
type: string
178+
```
179+
180+
In this example, the server expects a plain text file.
181+
182+
The curl command below sends a request to the server with a text file in the body:
183+
184+
```bash
185+
curl -X POST "https://api.example.com/text" \
186+
-H "Content-Type: text/plain" \
187+
-d "Hello, World!"
188+
```
189+
190+
### CSV Media Type
191+
192+
The example below shows a `content` object with a CSV media type:
193+
194+
```yaml
195+
content:
196+
text/csv:
197+
schema:
198+
$ref: "#/components/schemas/Drink"
199+
```
200+
201+
In this example, the server expects a CSV file representing a drink.
202+
203+
The curl command below sends a request to the server with a CSV file in the body:
204+
205+
```bash
206+
curl -X POST "https://api.example.com/csv" \
207+
-H "Content-Type: text/csv" \
208+
-d "Mojito,White Rum,50,Lime Juice,20,Mint Leaves,10"
209+
```
210+
211+
### Multipart Form Data
212+
213+
The example below shows a `content` object with a multipart form data media type:
214+
215+
```yaml
216+
content:
217+
multipart/form-data:
218+
schema:
219+
properties:
220+
photo:
221+
description: A photo of the drink.
222+
type: string
223+
format: binary
224+
recipe:
225+
description: The recipe for the drink.
226+
type: string
227+
name:
228+
description: The name of the drink.
229+
type: string
230+
encoding:
231+
photo:
232+
contentType: image/jpeg, image/png
233+
headers:
234+
Content-Disposition:
235+
description: Specifies the disposition of the file (attachment and file name).
236+
schema:
237+
type: string
238+
default: 'form-data; name="photo"; filename="default.jpg"'
239+
allowReserved: false
240+
recipe:
241+
contentType: text/plain
242+
headers:
243+
Content-Disposition:
244+
description: Specifies the disposition of the file (attachment and file name).
245+
schema:
246+
type: string
247+
default: 'form-data; name="recipe"; filename="default.txt"'
248+
allowReserved: false
249+
name:
250+
contentType: text/plain
251+
headers:
252+
Content-Disposition:
253+
description: Specifies the disposition of the field.
254+
schema:
255+
type: string
256+
default: 'form-data; name="name"'
257+
allowReserved: false
258+
```
259+
260+
In this example, the server expects a form data request with a photo of the drink, the recipe for the drink, and the name of the drink. The `encoding` field provides additional information about each part, such as the content type, headers, and whether reserved characters are allowed.
261+
262+
The curl command below sends a request to the server with a photo file, a recipe file, and the name of the drink in the body:
263+
264+
```bash
265+
curl -X POST "https://api.example.com/drinks" \
266+
-F "[email protected];type=image/jpeg" \
267+
-F "[email protected];type=text/plain" \
268+
-F "name=Mocktail"
269+
```
270+
271+
## OpenAPI Content Best Practices
272+
273+
When designing APIs with OpenAPI, consider the following best practices for content and media types:
274+
275+
- Where possible, use the most specific media type for your content. For example, prefer `application/json` over `application/*` if your content is JSON.
276+
- When using OpenAPI 3.1, provide at least one example for each media type using the `examples` keyword to help clients understand the expected content and enrich the API documentation.

0 commit comments

Comments
 (0)