Sending binary data along with a REST API request
The problem I would like to discuss is an API call, where you need to send binary data (for example multiple images) and some metadata information together. There are various ways you can approach this, and I will describe them briefly. Then I will go into more detail on multipart/form-data requests and how they can help you with the mentioned task.
Approach 1 – Send metadata and files in separate requests
The steps could be this:
- Send metadata to server
- Server stores metadata and generates an unique URL, to which files should be uploaded. Sends the URL in response.
- Client posts files to specified URL
This may be a good approach in a scenario, where you don’t need to receive the files right away together with the metadata. This enables the client to upload some initial files, then later add some more. This could be a good approach if you are creating a new photo album (metadata), then adding photos to it.
Approach 2 – Send metadata and files together in one request
There are some cases however when metadata and files are one entity and neither makes sense on its own. In this scenario you want to take some action on the whole client request data right away. Let’s say you are creating a service that combines some images into one, calculates some statistics, etc. If you used approach 1 in this scenario, you need to manage state between client requests. This can be complex and may hurt your scalability.
Fortunately you can send all data in one request if this is what makes the most sense. Here are a few ways to do this:
JSON / XML
Probably the easiest and most compatible way to send the data is to serialize it to JSON or XML. Also the binary data, which means getting +33% in message size due to BASE64 compression. This may be just fine in some cases.
BSON
However if the extra message size is not something you can put up with, then you can use a form of binary serialization. With ASP.NET WebAPI 2.1 you’ll get BsonMediaTypeFormatter out of the box, which will help you use BSON serialization (see http://bsonspec.org/). On the client side, you can use JSON.NET to do the serialization of the request message.
With some effort you should also be able to use Google’s protobuf protocol, which may be more efficient according to this blog post.
multipart/form-data
In some cases, maybe for compatibility reasons, you’ll not be able to use modern binary serialization like BSON or protobuf. In those cases you can still avoid sending binary data in BASE64 encoded string. You can use multipart/form-data request, effectively simulating HTML forms with file uploads behavior. This is a bit more complex than the previous approaches, so I would like to go into more detail.
But before that, I should mention, that this approach is not semantically correct. By using the Content-Type multipart/form-data you state, that what you send is actually a form. But it is not. It is rather some custom data format and for that, the most appropriate content type seems to be multipart/mixed (see the RFC). The HttpClient library for .NET won’t have any problems handling different subtypes of multipart/* MIME type, but for other platforms, it may not be true. I have seen some libraries (for Python for example), which had multipart/form-data content type hardcoded. So in this case you have two options: either write your own client library or give up being semantically correct and go with multipart/form-data. I can live with the latter.
So how to put some metadata together with multiple files into one request? Look at this example:
POST http://127.0.0.1:53908/api/send HTTP/1.1
Content-Type: multipart/form-data; boundary="01ead4a5-7a67-4703-ad02-589886e00923"
Host: 127.0.0.1:53908
Content-Length: 707419--01ead4a5-7a67-4703-ad02-589886e00923
Content-Type: application/json; charset=utf-8
Content-Disposition: form-data; name=imageset{"name":"Model"}
--01ead4a5-7a67-4703-ad02-589886e00923
Content-Type: image/jpeg
Content-Disposition: form-data; name=image0; filename=Small-Talk-image.jpg
...image content...
--01ead4a5-7a67-4703-ad02-589886e00923
Content-Type: image/jpeg
Content-Disposition: form-data; name=image2; filename=url.jpg...image content...
--01ead4a5-7a67-4703-ad02-589886e00923--
Going from the top we have a part with name = imageset. This part contains the metadata. It has JSON content type and a serialized JSON object. Then there are two parts containing image data with names image0 and image1. Those two additionally specify: image filename and image type (in Content-Type header).
The server, after receiving such request, can distinguish metadata and image data by looking at the part names (the names are part of the API contract client needs to follow). Then it can put the request together and execute a controller action passing in received data.
So how to actually implement this using ASP.NET WebAPI? (you can look at the code at Github)
Let’s start quickly with the definition of the data passed around:
public class ImageSet { public string Name { get; set; } public List<Image> Images { get; set; } } public class Image { public string FileName { get; set; } public string MimeType { get; set; } public byte[] ImageData { get; set; } }
Now, when implementing a WebAPI controller, we would like to receive and instance of the ImageSet as a parameter of the action.
[Route("api/send")]public string UploadImageSet(ImageSet model){ var sb = new StringBuilder(); sb.AppendFormat("Received image set {0}: ", model.Name); model.Images.ForEach(i => sb.AppendFormat("Got image {0} of type {1} and size {2} bytes,", i.FileName, i.MimeType, i.ImageData.Length) ); var result = sb.ToString(); Trace.Write(result); return result;}
Fortunately, WebAPI has a notion of MediaTypeFormatter, which basically lets you define logic for translating a certain type of request to a certain .NET type (and back). Here’s how to implement one for the ImageSet:
public class ImageSetMediaTypeFormatter : MediaTypeFormatter{ public ImageSetMediaTypeFormatter() { SupportedMediaTypes.Add(new MediaTypeHeaderValue("multipart/form-data")); } public override bool CanReadType(Type type) { return type == typeof (ImageSet); } public override bool CanWriteType(Type type) { return false; } public async override Task<object> ReadFromStreamAsync( Type type, Stream readStream, HttpContent content, IFormatterLogger formatterLogger) { var provider = await content.ReadAsMultipartAsync(); var modelContent = provider.Contents .FirstOrDefault(c => c.Headers.ContentDisposition.Name.NormalizeName() == "imageset"); var imageSet = await modelContent.ReadAsAsync<ImageSet>(); var fileContents = provider.Contents .Where(c => c.Headers.ContentDisposition.Name.NormalizeName().Matches(@"image\d+")) .ToList(); imageSet.Images = new List<Image>(); foreach (var fileContent in fileContents) { imageSet.Images.Add(new Image { ImageData = await fileContent.ReadAsByteArrayAsync(), MimeType = fileContent.Headers.ContentType.MediaType, FileName = fileContent.Headers.ContentDisposition.FileName.NormalizeName() }); } return imageSet; }}public static class StringExtenstions{ public static string NormalizeName(this string text) { return text.Replace("\"", ""); } public static bool Matches(this string text, string pattern) { return Regex.IsMatch(text, pattern); }}
By adding an entry to SupportedMediaTypes, you specify what content types this MediaTypeFormatter is able to handle. Then in CanRead and CanWrite you specify .NET types, to which (or from which) the request can be translated. ReadFromStreamAsync does the actual work.
Decoupling controller logic from request parsing logic gives you possibility to handle multiple request formats and you can let your clients choose the format they are most comfortable with by specifying appropriate Content-Type header.
Note: when you do the content.ReadAsMultipartAsync() call, you are using the MultipartMemoryStreamProvider, which handles all processing in-memory. Depending on your scenario, you may take different approach, for example MultipartFormDataStreamProvider, for which you’ll find a nice sample here.
The above code doesn’t do any request format validation for clarity of the example. In production, you’ll get all types of malformed requests from 3rd party clients, so you need to handle those situations.
How about some client code? First of all, on the client side we’ll make a small change in the ImageSet class:
public class ImageSet { public string Name { get; set; } [JsonIgnore] public List<Image> Images { get; set; } }
We want the JSON serialization to ignore Images collection, since they will be put into separate request parts.
This is how you could prepare a request to be sent:
static void Main(string[] args){ var imageSet = new ImageSet() { Name = "Model", Images = Directory .EnumerateFiles("../../../../../SampleImages") .Where(file => new[] {".jpg", ".png"}.Contains(Path.GetExtension(file))) .Select(file => new Image { FileName = Path.GetFileName(file), MimeType = MimeMapping.GetMimeMapping(file), ImageData = File.ReadAllBytes(file) }) .ToList() }; SendImageSet(imageSet);}
And here’s how to send it using HttpClient and Json .NET:
private static void SendImageSet(ImageSet imageSet){ var multipartContent = new MultipartFormDataContent(); var imageSetJson = JsonConvert.SerializeObject(imageSet, new JsonSerializerSettings { ContractResolver = new CamelCasePropertyNamesContractResolver() }); multipartContent.Add( new StringContent(imageSetJson, Encoding.UTF8, "application/json"), "imageset" ); int counter = 0; foreach (var image in imageSet.Images) { var imageContent = new ByteArrayContent(image.ImageData); imageContent.Headers.ContentType = new MediaTypeHeaderValue(image.MimeType); multipartContent.Add(imageContent, "image" + counter++, image.FileName); } var response = new HttpClient() .PostAsync("http://localhost:53908/api/send", multipartContent) .Result; var responseContent = response.Content.ReadAsStringAsync().Result; Trace.Write(responseContent);}
Summary
There are multiple ways to send mixed plain text / binary data to a REST API endpoint. The best what you can do while implementing public-facing API, is to let your clients choose format which is convenient for them. ASP.NET WebAPI has ways to facilitate that. multipart/form-data requests are a bit more complicated than whole-request binary serialization (BSON or protobuf), but may be more compatible with some platforms.
The code presented in this post can be found on Github. You’ll find there also client code samples for multipart/form-data scenario for Java, Python and node.js
