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” : “http://example.com/document.pdf”} ?

I’m trying to understand the difference between a URI and URL and keep with a RESTful philosophy. Admittedly, this is new to me so I may be misunderstanding some things.

Answer 1

This Section Assumes You Mean: How Do I Tell The User Where to Find a Binary Resource

The difference between a URI and a URL doesn’t have anything to do with binary vs. non-binary datatypes (see also).

If you’re returning mostly JSON, then a url entry is a common way to go. If you’re doing something more HTML/XML-ish, then something like a <link> element with a good rel attribute makes a lot of sense.

Obviously, if the client makes a GET request to the direct URL you gave them, then you should send them the file, unless they sent a bunch of content-negotiation headers that effectively preclude you from fulfilling their request. In that case, a 406 Not Acceptable response (or the official definition) makes a lot of sense.

If you meant something else by your question, please clarify.

A Rambling “Do It Like This” Section

First: ignore URL vs. URI. It doesn’t have anything to do with this. At all.

Next: If your problem is not “How do I link to a resource” (which might be affected by the stuff I’m about to discuss), but “What if my resource is just a PDF file”, you have all sorts of options for addressing it. First off, you need to step back and think more abstractly (a little). Your resource is almost certainly not “a PDF file”. It’s “a file uploaded by a user”, or “a PDF version of a report that I generate”, etc.

In the first case, you probably don’t have any representation of the resource beyond the binary they sent you, which is totally fine. You probably won’t need to perform any sort of content-negotiation when you receive a GET to the URL for that resource. Just send them the file, subject to the caveats about 406 I mention above.

In the second case, you might have all sorts of representations of this resource: CSV, HTML, LaTeX, you name it. In this case, when you receive a GET to the URL for the resource, you do need to do some content-negotiation, so you know whether to send them the PDF document, or something else. It’s possible that you might have a JSON representation of the resource that is just the raw data you use to generate the PDF.

In either case, it would be unexpected if you had a representation that was strictly metadata about the resource. If needed (often it is, sometimes it isn’t), explicit, external metadata (as opposed to metadata embedded within the binary resource, such as author and title info in PDFs) is most commonly modeled as a separate resource.

Finally, as @monitorjbl says: you probably don’t want to embed the binary data directly in a text format such as JSON or XML. There are ways of doing it, often involving the words “base64-encoded”, but it’s usually not the best approach. In general, you shouldn’t mix binary data and text data.