1

I'm designing my API, and I specify an optional API version in the URL

GET /Issuer/{certificate-name}/versions?api-version=2016-10-01[&maxresults]

Should I also have one specified in the HTTP Header (for flexibility)?

What should I do if there is a conflict between the two approaches?

makerofthings7
  • 60,103
  • 53
  • 215
  • 448
  • What's the value of it being optional to begin with (everyone client *some* version of the API)? What's the value of having two separate ways of specifying it? – sisyphus Jan 12 '17 at 00:19
  • No specified value equals the latest version. The value of having two different expressions is to allow REST -idealogical / fundamentalist customers to get the functionality they want. In this sense I'm an ISV, and I'm weighing the need to accommodate both perspectives. @sisyphus – makerofthings7 Jan 12 '17 at 05:27
  • I find allowing version in the query parameters pretty useful especially for testing purpose in the browser. I like the idea to be able to just "click" a link to show me how the API replies using my favorite browser and its JSON Extension. In case of conflicts, you may either returns a 400 with an error indicating the reason, or give a priority to one of them (I would give the queryParameter more value than the header because it is likely to be used to override any existing configuration in the case of a test). However, beware of the API version vs Resource Representation version. – Boris Guéry Jan 16 '17 at 14:00

1 Answers1

1

There is no obvious advantage to allowing an input of API version from 2 different input methods (querystring, and Header). However, the disadvantage here is conflict resolution if both are specified by the client.

There is no right or wrong way of where an API version should be specified, whether in the header or the querystring. But keep in mind that URLs require parsing, while mostly done the by framework, but still a compute resource you are spending to parse the URL to extract the value from.

I (personally) prefer using the header out of simplicity. Plus it feels more cleaner to keep the URL as an address only to point to the function/intent of the client.

Bishoy
  • 3,915
  • 29
  • 37