title: Mixed binary and non-binary HTTP resource
body: <p>I am developing a RESTful HTTP API based on ASP.NET Core 2 and the service will be used by a web frontend.</p>
  
  <p>In the API there is a resource representing a file. It comes with some meta-data (id, name, folder) and can optionally contain raw binary data representing the file contents. The rest of the API uses JSON.</p>
  
  <p>What is the modern approach to representing this resource in both requests and responses? The options I found so far are:</p>
  
  <h3>JSON with base64-encoded data</h3>
  
  <p><strong>Pros:</strong> Easy to implement and use</p>
  
  <p><strong>Cons:</strong>  The binary data can be up to multiple GB in size and Base64 would therefor massively inflate traffic as well asupload and download times, additonally the data would have to be encoded and decoded which would make the process rather slow</p>
  
  <h3>Split the resource into a JSON and binary subresource</h3>
  
  <p><strong>Pros:</strong> Easy to implement and use</p>
  
  <p><strong>Cons:</strong> Two requests must be made to access all information</p>
  
  <h3><a href="http://bsonspec.org/" rel="nofollow noreferrer">BSON</a></h3>
  
  <p><strong>Pros:</strong> No Base64</p>
  
  <p><strong>Cons:</strong> Not as easy to handle on both server and client side as JSON, data is binary even when only non-binary data is sent, has to be encoded and decoded, requires additional dependencies, format would be different from the rest of the API</p>
  
  <h3>multipart/form-data with JSON and binary data</h3>
  
  <p><strong>Pros:</strong> Binary and non-binary data can be split into JSON and binary data</p>
  
  <p><strong>Cons:</strong> Hard to handle, format would be different from the rest of the API</p>