Deploying Multipart form data endpoint in AWS API gateway via OpenAPI document

What is Multipart/form-data content type — It’s a special way to package up form data, especially when it includes things like big text files ,pictures, videos, non-ASCII, binary data or lots of text. Instead of sending everything in one big chunk, multi-part form data breaks it into smaller parts.Each part having its own content type and boundary marker.

POST /upload HTTP/1.1
Host: example.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="text_field"example -“x-amazon-apigateway-binary-media-types”: [ “application/octet”, “image/jpeg” ] or “x-amazon-apigateway-binary-media-types”:“*/*” ] or text/html

AWS API Gateway Setup

I am taking Private Rest API as an example to demonstrate to handle endpoint with files, openapi document is used to deploy apigateway here (creating via console is not used). And back end api is deployed in openshift.

Below are the important settings we need to take care in openapi document

1. x-amazon-apigateway-binary-media-types

2. OpenAPI document with below settings

consumes:multipart/form-data

in: formData

x-amazon-apigateway-integration -type as http_proxy

x-amazon-apigateway-binary-media-types should be included as a top-level vendor extension to the OpenAPI document.

Depending on the requirement we need to set values for x-amazon-apigateway-binary-media-types

Sample values:

“x-amazon-apigateway-binary-media-types”: [ “application/octet”, “image/jpeg” ]

“x-amazon-apigateway-binary-media-types”: [ “text/html”]

“x-amazon-apigateway-binary-media-types”: [ “*/*”]

Sample open api document (Swagger.yaml)

x-amazon-apigateway-binary-media-types:
- "*/*"  
'/testmultipart/filehandling/{fileId}':
post:
        summary: File handling
        operationId: postFile
        consumes:
          - multipart/form-data        
        produces:
          - application/json
        parameters:
          - name: fileId
            in: path
            description: FileId
            required: true
            type: integer
            format: int32
          - name: Authorization
            in: header
            description: Authorization 
            required: true
            type: string
          - name: file
            in: formData
            description: file
            required: true
            type: file
 
        security:
        - api-gateway-authoriser: []   
        x-amazon-apigateway-integration:
          connectionType: "VPC_LINK"
          type: "http_proxy"
          connectionId: 
            Ref: VPCLink
          httpMethod: "POST"
          uri: 
             Ref: backendendpointurl
          responses:
            "2\\d{2}":
              statusCode: "200"
          passthroughBehavior: "when_no_match"
          requestParameters:
            integration.request.header.Authorization: method.request.header.Authorization
            integration.request.path.FileId: method.request.path.FileId

Backend spring boot endpoint

@RequestMapping(value = "/testmultipart/filehandling/{fileId}", method = RequestMethod.POST)
@ResponseBody
public ResponseEntity<?> uploadFile(@PathVariable String fileId,
    @RequestParam("file") MultipartFile file) {

  try {    
    // ...
  }
  catch (Exception e) {

  }

Once API is deployed we can see in API settings tab binary media type is set

And we can view method request ,integration request in api gateway console to verify all required settings are in place for multipart form data.