What is a good way to transfer binary data to a HTTP REST API service?

rest http restapi
erotsppa picture erotsppa · Oct 2, 2009 · Viewed 62.7k times · Source

We are extending our HTTP REST API to allow clients to upload picture (for the purpose of this question, assuming binary data). So far we have only allowed simply strings in our API parameters. What is a good way to allow them to upload binary data? Would it be to request for the base64 encoded form? Would the URL become too long for the web server to handle?

Any suggestions/best practices?

Answer

Eugene Osovetsky picture Eugene Osovetsky · Oct 2, 2009

Just send the binary data as-is in a POST body, but with the appropriate Content-Type header (e.g. image/jpeg) - I think this is the most "RESTful" way.

(In general, as a rule of thumb when designing REST services, the more you work with the HTTP protocol as-is instead of trying to overlay something unnecessary and complex on top of it like base64, the better. HTTP is the ultimate RESTful protocol, and Content-Types allow for different "Representations" in "REpresentational State Transfer")

Another possibility to keep in mind is accepting image URLs instead of actual physical files. This makes it harder for standalone apps that e.g. read the image off the user's drive, but make it easier for mashup-type apps where the image may be returned as a URL from another service.

You can allow both options of course.

Related questions

Which HTTP response code for "This email is already registered"?

I'm creating a RESTful API for creating users that enforces unique email addresses: Successful POST /users: HTTP 201 Created If I POST the same email address again, what should the response code be? Is 409 Conflict the appropriate response code?

Read More
How to expose a validation API in a RESTful way?

I'm generally a fan of RESTful API design, but I'm unsure of how to apply REST principles for a validation API. Suppose we have an API for querying and updating a user's profile info (name, email, username, password). We've deemed …

Read More
Why isn't HTTP PUT allowed to do partial updates in a REST API?

Who says RESTful APIs must support partial updates separately via HTTP PATCH? It seems to have no benefits. It adds more work to implement on the server side and more logic on the client side to decide which kind of …

Read More