Hacker News new | past | comments | ask | show | jobs | submit login

That's extremely fussy compared to versioning the endpoints. Harder to test, harder to implement, and delivers no real benefit.



How exactly? How different it would be to pass a header instead of switching path ?

Im was writing such tests in spock and pacts.io and it was extremely easy to do both.


For the client, it's only marginally more difficult because you have to specify an extra header--since you'd have to specify the path anyway, versioning via path gives the client one less thing to specify.

For the server, it's annoying because every backend framework I've encountered ultimately boils down to "here is a function that gets called when the server receives a request to a given path". If you're versioning by path, you just write a new function for the new path. If you version by header, now you have to have a single request-handling function that performs conditional logic based on a request header--at which point I would probably just dispatch to separate functions for each version, which is exactly what path-based versioning would give me for free.

I'm also not exactly sure how, if at all, it's possible to document this type of behavior in OpenAPI/Swagger, if that's of any concern or relevance.

All in all, versioning by header isn't dramatically more annoying than versioning by path, but I see virtually zero concrete benefit from incurring the cost in the first place.


I think there is more than enough resources on the web to understand stand points of each of those solutions.

For me it seems like those are just tools created to tackle specific problems. Each has own pros and cons. Depending on usecase url based versioning may be worse than mime one. And vice versa.

I just wanned to point out that api versioning can be done equally easly in both ways.


It’s not “equally easy” though. I’m asking what the pros are, of versioning by header, and I’m not actually hearing a sensible response.


From the article I posted:

"Using the URI is the most straightforward approach (and most commonly used as well) though it does violate the principle that a URI should refer to a unique resource. You are also guaranteed to break client integration when a version is updated."

So versioning with content headers is useful when

* it's really important that there is a one to one mapping between a URI and a resource (not /v1/customer/1 and /v2/customer/1 URIs which both refer to customer 1). I'm not familiar enough with API construction to know why this might be important, but maybe system clarity?

* You have far flung clients that are not easy to update (iot, mobile apps, software that needs to be manually configured) and you want all clients to always go to the same URI (perhaps for whitelisting through a client firewall).


> it's really important that there is a one to one mapping between a URI and a resource (not /v1/customer/1 and /v2/customer/1 URIs which both refer to customer 1). I'm not familiar enough with API construction to know why this might be important, but maybe system clarity?

This isn't important unless you take "True REST" seriously. This notion is a fussy little hobgoblin that most people rightly dispense with.

> You have far flung clients that are not easy to update (iot, mobile apps, software that needs to be manually configured) and you want all clients to always go to the same URI (perhaps for whitelisting through a client firewall).

Surely if I'm not updating some of the clients, they can just continue using the v1 endpoint while other clients use a v2 endpoint. I don't actually see how this helps.




Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | Legal | Apply to YC | Contact

Search: