Multipart File Upload Endpoint Generation

As of version 1.5, the Framework now allows Multipart endpoints for file upload to be generated using RAML in a similar way to the other endpoint generation.

The Raml

/cases/{caseId}/casedocuments:
post:
  description: |
    Upload Case Documents
    ...
    (mapping):
      requestType: multipart/form-data
      name: staging.command.upload-case-documents
    ...
  body:
    multipart/form-data:
      formParameters:
        # This name is the name of the file part and, once the file is stored and 
        # we have an id for the file, will be used as the name of the field 
        # containing the file id in your JsonEnvelope
        caseFileId:  
          description: The id of the newly stored case document
          type: file # this is mandatory and must always be set to 'file'
  responses:
    202:
      description: Request accepted
    400:
      description: Bad Request
    500:
      description: Internal Server Error

This pretty much matches the RAML for other endpoint generation. It starts with the URL path (with any path parameters) and contains the mapping to your command name: in this case staging.command.upload-case-documents.

The requestType must always be multipart/form-data

Next is the body. This too must be multipart/form-data. Then the form parameters which must contain one form parameter who's name is the name used for the file part/field name in the JsonEnvelope. In this case the name is set to caseFileId

The type of the form parameter must be set to file. This is required by RAML to let it know we are dealing with a multipart endpoint here

filePartName/fieldName

The endpoint generation needs to link the file part name in the multipart request with a name for the fileId field in the resuting JsonEnvelope. It is very important therefore, to ensure that the form parameter name in the RAML and the filePart name in your rest client match. Failure to ensure they match will result in a BadRequestException and a HTTP 400 as a response