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

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: 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. I want the new API to be the default when inventory goes stable. 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. 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