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

Sean Dague sean at dague.net
Tue Jan 21 17:32:11 UTC 2014

On 01/21/2014 11:29 AM, Mark McLoughlin wrote:
> 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
> wrong-headed.

They are if they are drive by. They put a burden on the Tempest project
in maintaining code to validate them, they put a burden on our overall
testing load, by slowing down changes for everyone. They put a burden on
new features in the codebase by adding complexity.

We have not, in 2 years of Nova development, seen contributors show up
to strongly enhance that data payload.

What we have seen is thousands of engineering hours spent trying to make
it not explode. We've seen over a hundred thousand hours of machine time
spent validating it. As we sit at a gate queue of 137 and 50 hrs deep,
starved for resources, these aren't theoretical impacts, these are real

And they aren't transient. It won't just be better next week.

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

I believe in user contracts. If we documented that v2 worked this way,
it was important to make it actually work that way. Not reneg on our
statement. Maybe that was the wrong call, but it is something I believe
pretty strongly.

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

I think it is a real issue, because it means that projects are producing
an interface that "they never use", anywhere, for real.

I'll agree that it's shadow validation, by having that actually be the
wire protocal that people my use when doing "nova boot" in their local
cluster, but that's a huge gap.

And the reason it's not in those clients... is because it's expensive to
write, and people have better things to do. So why is it ok to write

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

Most people working on OpenStack today have a sponsor. This isn't a
primarily hobbiest project. And lots of people work on things they
believe the community thinks it needs, not just their personal itches.

Right now dual data formats are something that we've set an expectation
projects should have, so tons of energy is going into it. Not because
people are passionate about the feature, but because they are passionate
about the project.

I think we need to reset that expectation. Because nearly every instance
of people I know that have done XML tests in Tempest (for instance),
would way rather be doing other things in the project. But we've told
people it's important, so they are doing it.

The project leadership, be that the TC, PTLs, active contributors that
the community respects, do set priorities, both explicitly and
implicitely. And most of our community is pretty awesome and respects
that, and tries to do the right thing.

I just want to be able to tell them they don't need to keep doing this
thing, because we think it's not nearly as important in the future. If
people come forward later and want to volunteer for it anyway, good on
them. But lets not make it a first order concern to provide XML
interfaces on new APIs, because we can get huge wins if we don't.

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

Yes, and again, I think from a consistency point of view we should make
it a TC statement that we expect projects to have a solid, supported,
public JSON web service. I think just making that statement, explicitly
calling out JSON, and making no mention of XML would give projects the
freedom to take badly supported XML off their agenda for future
releases. Which I think, right now, people feel they can't do.


Sean Dague
Samsung Research America
sean at dague.net / sean.dague at samsung.com

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 547 bytes
Desc: OpenPGP digital signature
URL: <http://lists.openstack.org/pipermail/openstack-tc/attachments/20140121/111ac7d3/attachment.pgp>

More information about the OpenStack-TC mailing list