REST: HTTP headers or request parameters

http rest http-headers httprequest
Gevious picture Gevious · Oct 30, 2011 · Viewed 24.8k times · Source

I've been putting in some research around REST. I noticed that the Amazon S3 API uses mainly http headers for their REST interface. This was a surprise to me, since I assumed that the interface would work mainly off request parameters.

My question is this: Should I develop my REST interface using mainly http headers, or should I be using request parameters?

Answer

Aliostad picture Aliostad · Oct 30, 2011

The question mainly is whether the parameters defined are part of the resource identifier (URI) or not. if so, then you would use the request parameters otherwise HTTP custom headers. For example, passing the id of the album in a music gallery must be part of the URI.

Remember, for example /employee/id/45 (Or /employee?id=45, REST does not have a prejudice against query string parameters or for clean slash separated URIs) identifies one resource. Now you could use content-negotiation by sending request header content-type: text/plain or content-type: image/jpg to get the info or the image. In this respect, resource is deemed to be the same and header only used to define format of the resource.

Generally, I am not a big fan of HTTP custom headers. This usually assumes the client to have a prior knowledge of the server implementation (not discoverable through natural HTTP means, i.e. hypermedia) which always is considered a REST anti-pattern

HTTP headers usually define aspects of HTTP orthogonal to what is to be achieved in the process of request/response. Authorization header (really a misnomer, should have been authentication) is a classic example.

Related questions

Customize the Authorization HTTP header

I need to authenticate a client when he sends a request to an API. The client has an API-token and I was thinking about using the standard Authorization header to send the token to the server. Normally this header is …

Read More
Paging in a Rest Collection

I'm interested in exposing a direct REST interface to collections of JSON documents (think CouchDB or Persevere). The problem I'm running into is how to handle the GET operation on the collection root if the collection is large. As an …

Read More
Is REST DELETE really idempotent?

DELETE is supposed to be idempotent. If I DELETE http://example.com/account/123 it's going to delete the account. If I do it again would I expect a 404, since the account no longer exists? What if I attempt to DELETE …

Read More