[Hawkular-dev] How to gradually remove unfitting old REST APIs?

[Lukas Krejci]

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.


-- 
Lukas Krejci