9:54 p.m.
Normally I would say we should avoid breaking changes at all costs.
Even having to change the context root means having to rebuilt the
client in order to potentially get a fix that went along with the
breaking API change. But, in this case I really have to wonder how many
existing clients we're talking about outside of our own stuff.
Inventory is still in early releases and I don't want to see us have to
do extra work to support non-existing clients. If you care enough to
already be using HI I think you'd be OK with this early instability.
Remember, the changes to auth just broke *all* of the component releases.
On 5/24/2016 5:57 AM, Lukas Krejci wrote:
This stems from the mention of deprecating the REST API of inventory
and
making the new API the default one, forcing the existing clients to change.
I think this is a generic problem with the "emergent design" of iterative
development - sometimes the stuff you come up with turns out to be wrong and
you need to toss it away. At the same time, we need to minimize the "damage"
we do to the existing clients.
Let me just copy the relevant parts from the other thread and answer them
inline:
>> In 0.17.0.Final we will introduce a new REST API and will deprecate the
>> current one (most probably by moving it to
>> /hawkular/inventory/deprecated).
> This way you break all existing clients !
>
I know... At the same time Inventory is still not stable, it's 0.x.y, and the
current REST API really is broken in some ways.
I'd rather encourage clients to move away from it than keep it forever.
> You may either move the new api to a new prefix
I want the new API to be the default when inventory goes stable.
> Or use content negotiation where the new api gets a content of e.g.
> application/hawkular-inventory+json;v2
Again, I don't want to keep the old stuff around when inventory goes stable.
So having the new stuff as a v2 doesn't really make sense when v1 is going
away and will not be available in the future.
> A request without that content type gets the old endpoints and
> semantics.
> A request with that content type in the request will access the
> new endpoints (which may be separate or overlay the old ones)
> with potentially new data formats.
>
> This way clients can upgrade as they want
Content negotiation or new root context for the new API is certainly the clean
solution here, I can't argue that. It requires no change on the clients that
want to keep using the old API.
But I really want to prod the clients to upgrade, because I don't intend to
maintain the old API moving forward. So the "solution" is to actually MOVE the
old API to a new context root "/deprecated" (and I don't say it is the
ideal
one and I am open to be persuaded to use another).
This will have 2 consequences:
* if you want to keep using the old API, update your client to use the new
context root. This usually should be as simple as changing a constant in the
client with the new context root. After this change, the clients are free to
upgrade as they want.
* the new REST API remains "clean" - no need to specifically ask for it.
There are other options:
* When the old API is called, "compute" the new URI (if possible) and return
301. According to the spec, the clients should "relink" and use the new URI in
the future. The drawback here is that IMHO this is messy for the clients -
they don't have an idea WHY is this being done, nor are they explicitly told
about the new capabilities of the new API. Additionally, this can only work if
the old and new URIs are "mappable" and the actual content format doesn't
change.
* Add a Warning: 299 - "Deprecated. Consider upgrading to new API." header
(https://tools.ietf.org/html/rfc7234#section-5.5). If the clients look at the
response headers, this gives them the information about the deprecation. Con -
this might be missed by the clients.