[openstack-tc] recommendation to deprecate XML in new major API versions

Mark McLoughlin markmc at redhat.com
Tue Jan 21 16:29:59 UTC 2014

Just going back to the original email to put my reaction into
context ...

See inline.

On Tue, 2014-01-14 at 06:51 -0500, Sean Dague wrote:
> I started becoming really active in OpenStack during the Folsom cycle,
> and one of the big cleanups that Dan Smith and I did was at the very end
> of the cycle. There was 0 testing on the Nova XML API, and if you
> actually tried to use it, you got inconsistent responses, or stack
> traces. There were at least 6 critical bugs in that API because no one
> used it. That got fix by dual stacking the Tempest tests. We did this
> because we thought it would be embarresing for OpenStack to ship with an
> interface that it said supported, and that it didn't in any real way.

I value those contributions and I think everyone should.

> So I feel personally responsible for not letting XML die back in Nova v2
> by making it actually work.

Right, the Nova project could have explicitly deprecated Nova v2 XML
support and done something like:

  1) turn it off by default

  2) mention in the release notes that it's turned off by default 
     because of those bugs, with a link to the bugs

  3) state then that it would be removed in Grizzly if it didn't
     it hadn't been restored back to a basic level of usefulness

> Since then, many projects have followed Nova's lead and added XML APIs,
> which I think has been completely wrong headed.

I'd hate to see the TC take a position like that.

Accepting contributions which add useful XML support is not necessarily

> The only reason we
> didn't rip it out in Nova v2 is that it would be breaking in field
> compatibility without an API version bump. (Something else I feel
> strongly about).

I agree that backwards compat is important and it makes it a harder
call. But if, for example, it remained unusably broken in Folsom stable
then no-one could possibly have been using it with Folsom so removing it
in Grizzly shouldn't be such a backwards compat issue.

> However, the proliferation has costs (really costs in terms of people time).
>  - It increases the amount of code in the projects, it impacts the kind
> of data the JSON apis can return because they have to be XML friendly.
>  - It doubles the width of the validation interface (and XML validation
> is more code costly from python because it's not a direct serialization
> like python).
>  - It dramatically increases the width of the Documentation interface,
> as we need XML examples as well as JSON.

If a project's XML support was usable and well maintained, then I don't
see the issue with those.

Or put it this way, if projects add XML support they should be aware
they are taking on these additional costs. So long as they are aware,
that's fine.

> And it's not something that's currently universal.
>  - glance doesn't have an XML API

It's hardly the only lack of consistency between our APIs and at lest
this one is programmatically negotiable.

>  - the python clients don't implement XML data payload

Not necessarily an issue IMHO - that XML support is generally not widely
used or tested is probably the real issue you're alluding to.

> It also inhibits us doing really great things with our API, like making
> it end user fully discoverable with json schema (because then we'd need
> to figure out how we'd address that on the XML side, and that complexity
> tends to kill the innovation).

I could imagine adding discoverability to the json representation
without also adding it to XML ... but devils in the details.

As a general point, yes - new features often increases complexity and
has an impact on the ability to evolve other features.

> With a new Nova API on the horizon, I think it's time to make a TC level
> recommendation that XML payloads be deprecated, and that new major API
> versions don't include them.

I'd be happy to say we don't think it is required, that projects should
be aware of the burden of supporting additional representations and
perhaps outline the history of lack of active contributions to XML
support in OpenStack generally.

IOW, a cautionary tale but projects are free to make their own choice on
the matter.

> I'd like to bring this up for discussion either next week or the week
> after, because I think that the way every version of this discussion has
> gone in the past is a few people on a mailing list object, and we keep
> the XML API. However I think that's not serving our users well, because
> way too much energy gets diverted from really making our core JSON API
> excellent for users.

There's a touch of "contributor energy is a fungible resource" thinking
about that which I don't like - people will make their own decisions
about where to invest their energy.

But I think you're talking again about the existence of unmaintained XML
support forcing some people to spend energy on it - that is frustrating
and I absolutely agree that projects should be free to address that if
they feel they're trapped in that situation.


More information about the OpenStack-TC mailing list