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

[Jay Shaughnessy]

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.
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/hawkular-dev/attachments/20160524/976a6ad2/attachment.html