REST api, GET and timezone as param or header?

Question

What would be correct/preferred REST api design to fetch data that depends on timezone?

I was thinking about simply adding timezone as an URL param, so:

$ curl www.api.example.com/data?timezone="Europe/Amsterdam"

But someone suggested to use custom header for that in similar manner like github does:

$ curl -H "X-Time-Zone: Europe/Amsterdam" www.api.example.com/data

https://developer.github.com/v3/#using-the-time-zone-header

I wonder what are benefits of using header here instead of param? Is there any design pattern behind such decision?

Answer 1

It's entirely up to you, whether you wish to accept an input parameter in the path, querystring, header, or content body.

However, one could argue that a header makes sense when it is not the primary concern of the api you're calling. For example, if your api was specifically to retrieve the properties of a time zone, then I would recommend passing it on the url, either on the querystring as you suggested in your question, or on the path (www.api.example.com/timezone/europe/amsterdam).

Also note that the example you gave that uses the parameter in a header is a POST call. Though it's not prohibited, it usually doesn't make a lot of sense to pass querystring parameters in a POST. By passing the time zone as a header, the body of the message can focus on what is being posted.