Multipart Requests

Multipart requests combine one or more sets of data into a single body, separated by boundaries. You typically use these requests for file uploads and for transferring data of several types in a single request (for example, a file along with a JSON object). In OpenAPI 3, you describe a multipart request in the following way:

1
requestBody:
2
  content:
3
    multipart/form-data: # Media type
4
      schema: # Request payload
5
        type: object
6
        properties: # Request parts
7
          id: # Part 1 (string value)
8
            type: string
9
            format: uuid
10
          address: # Part2 (object)
11
            type: object
12
            properties:
13
              street:
14
                type: string
15
              city:
16
                type: string
17
          profileImage: # Part 3 (an image)
18
            type: string
19
            format: binary

You start with the requestBody/content keyword. Then, you specify the media type of request data. File uploads typically use the _multipart/form-data_ media type, and mixed-data requests usually use _multipart/mixed_. Below the media type, put the schema keyword to indicate that you start describing the request payload. You describe individual parts of the request as properties of the schema object. As you can see, a multipart request can include various data: strings, objects in JSON format, and binary data. You can also specify one or several files for uploading. (To learn more, see File Upload.) The example above corresponds to the following request:

1
POST /upload HTTP/1.1
2
Content-Length: 428
3
Content-Type: multipart/form-data; boundary=abcde12345
4

5
--abcde12345
6
Content-Disposition: form-data; name="id"
7
Content-Type: text/plain
8

9
123e4567-e89b-12d3-a456-426655440000
10
--abcde12345
11
Content-Disposition: form-data; name="address"
12
Content-Type: application/json
13

14
{
15
  "street": "3, Garden St",
16
  "city": "Hillsbery, UT"
17
}
18
--abcde12345
19
Content-Disposition: form-data; name="profileImage "; filename="image1.png"
20
Content-Type: application/octet-stream
21

22
{…file content…}
23
--abcde12345--

Specifying Content-Type

By default, the Content-Type of individual request parts is set automatically according to the type of the schema properties that describe the request parts:

Schema Property Type

Content-Type

Primitive or array of primitives

text/plain

Complex value or array of complex values

application/json

String in the binary or base64 format

application/octet-stream

To set a specific Content-Type for a request part, use the encoding/_{property-name}_/contentType field. You add encoding as a child of the media type property, one the same level where schema is located. In the example below, we set the contentType for the profileImage part of a multipart request to image/png, image/jpg:

1
requestBody:
2
  content:
3
    multipart/form-data:
4
      schema:
5
        type: object
6
        properties: # Request parts
7
          id:
8
            type: string
9
            format: uuid
10
          address:
11
            type: object
12
            properties:
13
              street:
14
                type: string
15
              city:
16
                type: string
17
          profileImage:
18
            type: string
19
            format: base64
20
      encoding: # The same level as schema
21
        profileImage: # Property name (see above)
22
          contentType: image/png, image/jpeg

Specifying Custom Headers

Parts of multipart requests usually do not use any headers, except for Content. In case you need to include custom headers, use the encoding/_{property-name}_/headers field to describe these headers (see below). For complete information on describing headers, see Describing Parameters. Below is an example of a custom header defined for a part of a multipart request:

1
requestBody:
2
  content:
3
    multipart/form-data:
4
      schema:
5
        type: object
6
        properties:
7
          id:
8
            type: string
9
            format: uuid
10
          profileImage:
11
            type: string
12
            format: binary
13
      encoding:
14
        profileImage: # Property name
15
          contentType: image/png, image/jpeg
16
          headers: # Custom headers
17
            X-Custom-Header:
18
              description: This is a custom header
19
              schema:
20
                type: string

This declaration matches the following request:

1
POST /upload HTTP/1.1
2
Content-Length: 428
3
Content-Type: multipart/form-data; boundary=abcde12345
4

5
--abcde12345
6
Content-Disposition: form-data; name="id"
7
Content-Type: text/plain
8

9
123e4567-e89b-12d3-a456-426655440000
10
--abcde12345
11
Content-Disposition: form-data; name="profileImage"; filename="image1.png"
12
Content-Type: image/png
13
X-Custom-Header: x-header
14

15
{…file content…}
16
--abcde12345--

Did not find what you were looking for? Ask the community
Found a mistake? Let us know