How to Accept File Uploads & Multipart data to an API

Receiving binary and multipart data to your API or HTTP Trigger.

In order to configure your API to receive file uploads and multipart data, you need to specify it in your OpenAPI specification in a strict manner. Performing this using HTTP Trigger is easier, but not always possible for use cases where an API is necessary.

Requirements

You will need access to a Frends Tenant with at least Editor role or similar permissions.

In order to implement the solutions explained here, some knowledge on C# programming and handling binary data is recommended but not mandatory.

Setting up API in Frends to accept binary data

In order to accept binary data, especially multipart form data, to your API operation, the API operation's requestBody must be exactly:

requestBody:
  content:
    multipart/form-data:
      schema:
        type: string
        format: binary

In order to accept a single file upload instead of varying multipart data, you can specify the file's content-type instead. For example to accept solely PDF file uploads:

requestBody:
  content:
    application/pdf:
      schema:
        type: string
        format: binary

Using type:string and format:binary as the requestBody's format enables you to use #trigger.data.httpContentBytesInBase64 reference value in your API Processes.

The whole incoming request body is provided as single byte array that is encoded in base64, even if you are expecting a multipart body. You will need to parse the byte data properly to access the content.

After setting up the API in Frends, you can start creating a Process (or modify existing Process) with API Trigger for the specified API operation and use #trigger.data.httpContentBytesInBase64 reference value in the Process to access the incoming request's body as a byte array with base64 encoding.

Using HTTP Trigger to receive binary data

Unlike APIs and API Trigger, HTTP Trigger is not used with an API Specification. Instead the #trigger.data.httpContentBytesInBase64 reference value is always available to use with HTTP Trigger, containing the whole incoming request's body as a byte array with base64 encoding.

Using binary data in Frends Process

Once an API has been configured for it or if using HTTP Trigger, the http request body is available as byte array as base64 encoded string from reference value #trigger.data.httpContentBytesInBase64.

Accessing the content from that can be divided into two sections: Using the data as a whole file if the only input is a single file, or parsing the content into parts if the incoming message was in multipart format.

Handling File Upload

Simplest way of handling a file upload scenario is by using Files.WriteBytes Task. This Task takes in the provided file contents as byte[] and writes it to a file in the local file system. The file is then available to use in other Tasks that expect a path to a file.

Alternatively for Tasks that expect the file contents directly as byte array, you can use the following piece of C# code to convert the received base64 string into a byte array. This same code is used for Files.WriteBytes Task.

Convert.FromBase64String(#trigger.data.httpContentBytesInBase64)

In case you need to perform more complex actions with the file or around the file saving, the following C# code can be used to write the base64 string into a file as binary content correctly and receiving the absolute path to the created file in local filesystem. This performs mostly the same action as the prebuilt Files.WriteBytes Task.

{
    // Get the base64 UTF8 string data from the trigger
    string base64Data = #trigger.data.httpContentBytesInBase64;

    // Convert base64 string to byte array
    byte[] imageBytes = System.Convert.FromBase64String(base64Data);

    // Define the file path to save the PNG image
    // Using a fixed file name in the current directory, can be changed as needed
    string fileName = "output.png";
    string absolutePath = System.IO.Path.GetFullPath(fileName);

    // Write the byte array to the file, overwriting if it exists
    System.IO.File.WriteAllBytes(absolutePath, imageBytes);

    // Return the absolute path of the saved file
    return absolutePath;
}

With the file written to disk, you can use the file path to give it as input to other Tasks, such as the AI Connector.

Providing a written file as filepath to AI Connector.

Handling the payload as Multipart Form Data

Because of how Frends APIs are currently set up, the whole multipart message will be provided as single byte array in base64 string. In order to safely split it into different parts while retaining possible binary content intact without encoding and decoding affecting the content, the split has to be done while it is in binary format.

To perform this, there are two different options. Easier to implement is by using a Frends Task for it, called ParseMultipartRequest. This Task performs splitting the received binary data into different parts with their headers, while retaining binary data intact.

Using ParseMultipartRequest Task to convert incoming binary payload into Multipart.

The Task itself provides all the included files, including text-only files, as separate byte arrays, that may then be written to a file by using Files.WriteBytes Task, or provided to other Tasks as byte array or base64 string depending on your use case. Any separate form fields will be provided as JSON array of parameters.

Alternatively to using the ready made Task, if it fails to parse your specific multipart content or format, you can write your own C# code to perform the same or similar byte array based splitting of the payload.

For example, this C# code handles basic scenarios of parsing JSON and text content into JSON objects, while parsing binary files such as PDF documents and PNG images into separate byte arrays that are directly written to a file, in order to use them with Tasks that expect a file path to a file. It is using same or similar logic as the ready-made Task for handling Multipart requests, but written in format that allows it to be used in a Code Task in Frends Process.

{
    JObject ParseMultipartBase64(string base64Input, string folderPath)
    {
        byte[] rawBytes = System.Convert.FromBase64String(base64Input);

        int firstLineEnd = System.Array.IndexOf(rawBytes, (byte)'\n');
        string boundaryLine = System.Text.Encoding.UTF8.GetString(rawBytes, 0, firstLineEnd).Trim();
        string boundary = boundaryLine;

        byte[] boundaryBytes = System.Text.Encoding.UTF8.GetBytes(boundary);
        var parts = SplitBytes(rawBytes, boundaryBytes);

        var resultParts = new Newtonsoft.Json.Linq.JArray();

        foreach (var part in parts)
        {
            if (part.Length == 0) continue;

            int headerEnd = FindHeaderEnd(part);
            if (headerEnd == -1) continue;

            string headers = System.Text.Encoding.UTF8.GetString(part, 0, headerEnd);
            byte[] content = new byte[part.Length - headerEnd - 4];
            System.Buffer.BlockCopy(part, headerEnd + 4, content, 0, content.Length);

            string contentType = ExtractHeader(headers, "Content-Type");
            string name = ExtractName(headers);

            var partObject = new Newtonsoft.Json.Linq.JObject
            {
                ["name"] = name,
                ["contentType"] = contentType
            };

            // Default to text/plain if Content-Type is missing
            if (string.IsNullOrEmpty(contentType))
            {
                contentType = "text/plain";
            } 
            
            if (contentType != null && contentType.Contains("application/json"))
            {
                string jsonText = System.Text.Encoding.UTF8.GetString(content);
                partObject["content"] = Newtonsoft.Json.Linq.JObject.Parse(jsonText);
            }
            else if (contentType != null && contentType.StartsWith("text/"))
            {
                string text = System.Text.Encoding.UTF8.GetString(content);
                partObject["content"] = text;
            }
            else
            {
                System.IO.Directory.CreateDirectory(folderPath);
                string fileName = ExtractFilename(headers) ?? $"uploaded_{System.Guid.NewGuid().ToString()}.bin";
                string filePath = System.IO.Path.Combine(folderPath, fileName);
                System.IO.File.WriteAllBytes(filePath, content);
                partObject["filePath"] = filePath;
            }

            resultParts.Add(partObject);
        }

        return new Newtonsoft.Json.Linq.JObject
        {
            ["parts"] = resultParts
        };
    }

    string ExtractFilename(string headers)
    {
        foreach (var line in headers.Split(new[] { "\r\n", "\n" }, System.StringSplitOptions.None))
        {
            if (line.StartsWith("Content-Disposition", System.StringComparison.OrdinalIgnoreCase))
            {
                var match = System.Text.RegularExpressions.Regex.Match(line, "filename=\"([^\"]+)\"");
                if (match.Success)
                    return match.Groups[1].Value;
            }
        }
        return null;
    }

    string ExtractHeader(string headers, string key)
    {
        foreach (var line in headers.Split(new[] { "\r\n", "\n" }, System.StringSplitOptions.None))
        {
            if (line.StartsWith(key, System.StringComparison.OrdinalIgnoreCase))
            {
                var parts = line.Split(':', 2);
                if (parts.Length == 2)
                    return parts[1].Trim();
            }
        }
        return null;
    }

    string ExtractName(string headers)
    {
        foreach (var line in headers.Split(new[] { "\r\n", "\n" }, System.StringSplitOptions.None))
        {
            if (line.StartsWith("Content-Disposition", System.StringComparison.OrdinalIgnoreCase))
            {
                var nameMatch = System.Text.RegularExpressions.Regex.Match(line, "name=\"([^\"]+)\"");
                if (nameMatch.Success)
                    return nameMatch.Groups[1].Value;
            }
        }
        return null;
    }

    int FindHeaderEnd(byte[] data)
    {
        for (int i = 0; i < data.Length - 3; i++)
        {
            if (data[i] == '\r' && data[i + 1] == '\n' &&
                data[i + 2] == '\r' && data[i + 3] == '\n')
            {
                return i;
            }
        }
        return -1;
    }

    List<byte[]> SplitBytes(byte[] source, byte[] delimiter)
    {
        var parts = new System.Collections.Generic.List<byte[]>();
        int start = 0;

        for (int i = 0; i <= source.Length - delimiter.Length; i++)
        {
            bool match = true;
            for (int j = 0; j < delimiter.Length; j++) {
                if (source[i + j] != delimiter[j])
                {
                    match = false;
                    break;
                }
            }

            if (match)
            {
                int length = i - start;
                if (length > 0)
                {
                    byte[] part = new byte[length];
                    System.Buffer.BlockCopy(source, start, part, 0, length);
                    parts.Add(part);
                }
                start = i + delimiter.Length;
                i = start - 1;
            }
        }

        if (start < source.Length)
        {
            byte[] part = new byte[source.Length - start];
            System.Buffer.BlockCopy(source, start, part, 0, part.Length);
            parts.Add(part);
        }

        return parts;
    }

    return ParseMultipartBase64(#trigger.data.httpContentBytesInBase64, "/frends-shared-data/binary-test/");
}

The code performs splitting the payload into parts without converting the payload into string, as additional conversions may break some binary content that also include text encoding. The multipart headers are assumed to be UTF-8 encoded, which is standard for Frends.

With the byte array payload converted and split into proper multipart message in either way, the content is ready to be used in your Frends Process. If you skipped it, you can read more on how to use the received binary data from the section above, called Handling File Upload.