REST API and delivering a binary resource

Question

What is the convention to deliver a binary resource (like a pdf file) with a REST API? Do you just return a URL to the resource in your JSON or XML response, e.g., {\"url\"

Answer 1

Binary or not, your REST resources should be described with hypermedia types.

• if your REST clients PUT/POST resources in msgpack format, the REST server can still read this message and update/create the resource. So why not.
• if your REST clients PUT/POST resources in PDF format, my guess is you won't be able to extract all the information you need to create/update a resource properly. So, no.

In that last case, you may be dealing with a "Google drive"-like service: the those PDFs aren't your resources per se, and should be linked by your actual resource (i.e. the URL should be within your resource).

Even if Google Drive may not be the perfect REST API (API reference), it's dealing with both JSON resources and actual binary files.