geemus
HTTP API Design

Updated 7 months ago

Kenneth LeFebvre (@kenlefeb) started discussion #6

3 months ago · 0 comments

Open

Require Versioning in the Accepts Header

I completely agree with your recommendation to "require a version be specified with all requests", however you assert that the best way to do this is in the headers, such as in the Accept header, without really explaining why you think this is the best place to put the version.

Very many APIs in the wild, put their version in the URI path, and that seems to me to be more obvious and in your face, to be sure the developer understands what he's doing. Perhaps I'm missing something about why adding a version to the Accept header is better. Can you clarify please?

Otherwise, thanks for this outstanding resource. I've recommended it to others quite a bit.

Wesley Beary @geemus commented 3 months ago

Sure, I'll do my best to clarify my own stance on it here and we can discuss. Certainly happy to work on including more explanation once I've gotten it described to our satisfaction.

In many ways it boils down to how one interprets the different areas. I tend to think about it as the URI providing a "what am I referring to" whereas headers define "how am I referring to it" (other headers fall pretty clearly into this pattern already). In this particular case, I would also prefer a single URI/URL to always refer to a particular thing and headers to define how you would like to interact with it, rather than having multiple different references that all point to thes same thing. As an extension to some of this, I also prefer things like the what/how divide to be hard and fast rules, in the hopes that it might reduce the amount of discussion/argument/etc that will end up happening around particular cases.

I agree that it can make it a bit less obvious/in-the-face of the developer (depending on the http client they are using), but developers use headers for a lot of other things already, so hopefully it should be an oversight that would be quickly realized and corrected.

Does that help clarify? Certainly happy to discuss further and dig into things if needed.

Kenneth LeFebvre @kenlefeb commented 3 months ago

Yes, that is a great explanation. I had not considered that perspective, but it makes a lot of sense and I think I really like it.

In most of my experience, the version of the request matches the version of the response, but there have been a few strange cases where I had to change one without the other (for instance, the back-end algorithms needed additional info in the request, but I couldn't change the code that parsed the response). It seems to me that using the Accepts header specifies the version of the response without really specifying the request version. Extrapolating your example, I suppose if I had to, I could add a version to the Content-Type header, right? How would you propose handling the absence of version parameters in those headers? Always assume the most current version?

Thanks for your quick response!


to join this conversation on GitBook. Already have an account? Sign in to comment
Notifications

You’re not receiving notifications from this thread.


1 participant